> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ca.cryptoprocessing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment requests integration guide

Let your customers pay crypto via a convenient [payment request](https://docs.ca.cryptoprocessing.com/payment-requests.md) interface with rate lock, currency conversion, and easy refunds.

![Payment request flow: the merchant creates a payment link, the customer pays on the hosted page, and the payment is confirmed by callback](https://mintcdn.com/cr-can/mbcsyiIu96I71U7S/images/payment-requests/payment-request-flow.jpg?fit=max\&auto=format\&n=mbcsyiIu96I71U7S\&q=85\&s=a91963546966c625f47f34dfcbca2c3a)

**1. Complete your onboarding**

Configure your account and get an API key, see [Initial setup](https://docs.ca.cryptoprocessing.com/initial-setup.md).

**2. Create a payment request**

When the customer wants to make a new purchase, send a request to [/payments/v1/requests](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/payments.md). Specify the required amount, [currency](https://docs.ca.cryptoprocessing.com/payment-requests.md#currency-selection) and [lifespan](https://docs.ca.cryptoprocessing.com/payment-requests.md#lifespan-and-rate-lock) for the payment request.

**request body example**

```json theme={null}
{
  "amount": "100",
  "currency": {
    "iso": "USD"
  },
  "life_time_duration": 360000,
  "end_user_email": "chris.customer@example.com",
  "description": "Order 0511",
  "sender_type": "legal",
  "sender_data": {
    "legal_name": "Example Customer",
    "country_of_registration": "CAN"
  }
}
```

**response body example**

```json theme={null}
{
  "data": {
    "id": "019d511c-9fd2-7e71-b534-74e8abd855f1",
    "amount": "100",
    "currency": {
      "iso": "USD"
    },
    "status": "created",
    "life_time": 1775542323,
    "end_user_email": "chris.customer@example.com",
    "description": "Order 0511",
    "payment_link": "https://payments.ca.cryptoprocessing.com/payment/lLXLZ6Q8lCwFFRbyW0C1ET",
    "user_fee_percent": 0,
    "rate_mode": "standard"
  }
}
```

**3. Let the customer navigate to the payment request interface**

The URL of the interface is provided in the [data.payment\_link](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/payments.md#response-data-payment-link) field of the API response. Depending on your payment flow, you can:

* navigate the customer to the payment request link in a new tab,
* generate a QR code based on the payment request link and display it to your customer,
* embed the payment link as an iFrame for quick on-page checkout.

For the customer's convenience, we recommend providing a link to the pending payment request somewhere on your site, too. This way, if the customer accidentally closes the payment request tab before finishing the payment, they will use the link to continue the process.

**4. Process the callback**

When you get the [payment\_request](https://docs.ca.cryptoprocessing.com/api-reference/callbacks/payment-request-callbacks.md) callback, update the purchase status on your site.

Make sure to cover all possible statuses of the callback. For a Failed or Expired payment request, consider showing a 'Retry' button that initiates a purchase of the same product again.

For a Paid payment request, you will see the requested amount as `payment_request_amount` and the actual paid amount as `currency_received`. These values may differ if you allowed [accepting underpayments](https://docs.ca.cryptoprocessing.com/payment-requests/underpayments.md#accept-underpayments) within a tolerance. Be sure to use `currency_received` if you need to perform an action based on the actual payment, such as adding the funds to the customer's balance.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.