Quickstart Guide

An introduction to making payments using the Convera API. You'll be up and running in no time!

Welcome to the Convera API Suite Quickstart Guide!

In this guide, you'll walk through the basic steps for verifying connectivity to the API, creating your first payments, and sending them to beneficiaries in more than 140 currencies and 200 regions.

Step 1 - Get Connected

To obtain your API keys, please contact the Convera onboarding team. Once complete, you can submit a Send Ping Request to verify connectivity to the API.

# GET /ping
$ curl https://masspay.api.convera.com/MassPayments/ping

Step 2 - Create a Batch

The first step in the payment journey is to Create a new Batch. A batch can hold payments of multiple currencies, up to a total of 10 currency pairs. There is a "soft" limit of 5,000 payments where performance degradation can be expected. There is no limit to the number of batches that can be created.

# PUT /customers/:id/batches/:id
$ curl https://masspay.api.convera.com/MassPayments/customers/customer_01/batches/batch_01

Step 3 - Add a Payment

Once a batch has been created, it can be referenced using the batchId to collect payments for processing. Each payment must have a unique payment ID across the Partner account or the payment will not be accepted. For payment payload structure, see Add Payment to Batch. For a list of required fields for processing, see Payment Validator Resource.

# PUT /customers/:id/batches/:id/payments
$ curl https://masspay.api.convera.com/MassPayments/customers/customer_01/batches/batch_01/payments

Step 4 - Check Payment

Once the payment has been submitted, it is validated according to the payment method, currency, origin, and destination country rules. Once the payment request receives a 202 Accepted code, you can begin querying the status of the payment to retrieve the final status. Validations happen asynchronously so there may be a slight delay in processing. Rejections will display a NotAccepted status and identify a problem field if applicable. Otherwise, a successfully validated payment will display a Created status. You can use the Get Payment by ID request to verify the status of a payment at any point in the workflow.

# GET /customers/:id/batches/:id/payments
$ curl https://masspay.api.convera.com/MassPayments/customers/customer_01/batches/batch_01/payments/payment_01

Step 5 - Quote the Batch

To retrieve a quote that includes payment subtotals, settlement amounts, and FX conversion rates, you can Create Quote for Payment Order. The API will automatically group payments with the same trade-settlement currency pairs together and offer a subtotal trade amount, settlement amount, and FX conversion rate for each pair.

# POST /customers/:id/batches/:id/quote
$ curl https://masspay.api.convera.com/MassPayments/customers/customer_01/batches/batch_01/quote

Step 6 - Commit the Order

After a successful payment quote request, the API will store the quoteId for 120 seconds. To finalize the payment order for processing, you can Commit Payment Order. The settlement method must be specified for each settlement currency included in the quote or the default settlement associated with the Customer account will be used. This default is established during Customer child account configuration under the Partner account.

# POST /customers/:id/batches/:id/orders
$ curl https://masspay.api.convera.com/MassPayments/customers/customer_01/batches/batch_01/orders

And there you have it--you have successfully sent your first payment! Continue exploring the API by visiting our API Reference.

What’s Next