Skip to main content

Payments Tutorial

The Payments API provides a set of endpoints that allow you to manage payments. This tutorial will guide you through the process of getting a payment quote, creating a payment with that quote, and retrieving the payment to check its status.

Creating a Payment Quote​

Before creating a payment, you should first create a payment quote. This can be done by making a POST request to the /api/v1/payments/quote endpoint. To create a payment quote, you need to provide the following details:

  • currency: The currency for the payment quote request. This must be a valid ISO 4217 code. For example, "USD".
  • country: The country for the payment quote request. For example, "US".

For more details, please refer to the Payment Quote API documentation.

Creating a Payment​

Once you have obtained a payment quote (see Getting a Payment Quote), you can proceed to create a payment. The payment creation process involves using the ID of the payment quote. This ID is included in the Payment object that you send in the body of the POST request to the /api/v1/payments endpoint.

In addition to the quoteId, each payment in the request must also include an externalRef. This externalRef should be a unique identifier generated by the user and will be treated as an idempotency key for the payment. This ensures that if a request is retried, duplicate payments are not created.

Here's the steps to create a successful payment:

  1. Obtain the quoteId from the PaymentQuote object that was returned when you created the quote.

  2. Create a Payment object, including the quoteId and other necessary details.

  3. Include this Payment object in the CreatePaymentsRequest array.

  4. Send a POST request to the /api/v1/payments endpoint with the CreatePaymentsRequest object in the body.

For more details, please refer to the Create Payment API documentation.

Retrieving a Payment​

You can retrieve the details of a payment by making a GET request to the /api/v1/payments/{id} endpoint. For more details, please refer to the Retrieve Payment API documentation.

Subscribing to Payment Events​

You can subscribe to updates across all payments by making a POST request to the /api/v1/payments/subscribe endpoint. For more details, please refer to the Subscribe to Payment Events API documentation.

Please note that if a webhook delivery does not succeed for any reason, we will attempt to resend it using an exponential backoff strategy over a period of up to 7 days. We consider a delivery successful when we receive a 200 status code in response.