Skip to main content

Collections Tutorial

The Collections API provides operations related to collections. This includes creating a collection, attaching payments to a collection, creating a collection quote, retrieving a collection, and subscribing to collection events.

Creating a Collection Quote​

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

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

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

Creating a Collection​

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

In addition to the quoteId, the collection 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 collection. This ensures that if a request is retried, a duplicate collection is not created.

Here's the steps to create a successful collection:

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

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

  3. Send a POST request to the /api/v1/collections with the Collection object in the request body.

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

Attaching Payments to a Collection​

To attach one or more payments to a specific collection, make a PUT request to the /api/v1/collections/{id}/payments endpoint. The request body should include a list of CollectionPayment objects. For more details, please refer to the Attach Payments API documentation.

Retrieving a Collection​

To retrieve a collection, make a GET request to the /api/v1/collections/{id} endpoint. For more details, please refer to the Get Collection API documentation.

Subscribing to Collection Events​

To subscribe to collection events, make a POST request to the /api/v1/collections/subscribe endpoint. The request body should include a SubscriptionRequest object. For more details, please refer to the Subscribe to Collection 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.