Skip to main content

​
Payout process

To help you get started with the payout process, we’ll walk through the steps of creating your first payout using our API. We’ll assume that you have completed the onboarding process, been whitelisted for API services, created your OAuth credentials, obtained an access token, and set up your webhooks for both collections and payouts. The following steps will guide you through the payout process:

​
Step 1: Create a customer

Before you can make any payouts, you need to associate them with a customer. Every payout (and collection) must be linked to a customer in the system.
  • Endpoint: /customer
  • Purpose: This endpoint bootstraps the customer record in our system.
  • Status: When a customer is first created, their status will be marked as "pending".
Make sure to save the customer_id returned from this endpoint as you’ll need it in future steps.
The customer’s country must match the identity document provided for KYC. Also note that only NON-VERIFIED customers can be fully updated. If a customer is already VERIFIED, only fields that are currently null can be updated.

​
Step 2: Upload documents for the customer

Once you have created the customer, the next step is to upload documents to verify their identity. The customer will remain in a "pending" state until their documents (especially id_file) are uploaded and verified.

​
2.1 Request pre-signed URLs for document upload

  • Endpoint: /file
  • Purpose: Provides a pre-signed URL that allows you to upload documents for the customer.
  • Request: Specify the customer_id and the file_category (e.g. identity, proof_of_address, liveness_check).
  • Response: You’ll receive a URL, a set of headers, and a file_id. The URL is where you will upload the actual document.

​
2.2 Upload the document

  • Method: Use the pre-signed URL to upload the document.
  • Request: Perform a PUT request to the pre-signed URL, uploading the document as a binary file using the URL and headers provided.
Repeat this process for each required document.

​
2.3 Add files to the customer

After uploading the documents, you’ll need to associate the uploaded documents with the customer using the file_id returned in the previous step.
  • Endpoint: /customer
  • Request: Pass the customer_id as a URL parameter, then include the file_id for each document in the request body.
  • Purpose: Updates the customer by attaching the uploaded files to their profile. Once the files are successfully added, the customer status will change to "verified".

​
Step 3: Create a payout

Now that the customer is verified, you can proceed to create a payout.
  • Endpoint: /payout
  • Purpose: Initiate a payout associated with the verified customer.
Before initiating a payout, ensure the following prerequisites are in place for a smooth experience — requirements vary depending on the destination currency.
The following requirements apply regardless of which currency you are sending to.Customer must be verifiedEvery payout must be linked to a verified customer. If your customer’s identity documents have not been uploaded and approved, the payout will be rejected. Make sure you have completed Step 1 and Step 2 above before attempting a payout.Wallet must existThe wallet_id you pass in the request must belong to your business. If the wallet does not exist or the ID is incorrect, the payout will fail.Sufficient balanceYour wallet must have enough funds to cover both the payout amount and any applicable fees. We recommend calling the fees breakdown endpoint first to confirm the total cost before initiating the payout.Amount must exceed feesIf you are specifying a from_amount (the amount you want to send), it must be greater than the total applicable fees. If the fees are equal to or exceed the amount, the payout will be rejected.Currency pair must be supportedThe combination of from_currency_id and to_currency_id must be an active, supported pair. If sending between those two currencies is not currently enabled, the payout will not go through.Payout method must be valid for the currencyEach currency supports specific payout methods (e.g. bank_transfer, interac, crypto, ach, wire). If you use a method that is not available for the destination currency, the request will be rejected.Business must not be under Enhanced Due DiligenceIf your business has been placed under Enhanced Due Diligence (EDD) review, all payouts will be blocked until the review is resolved. Contact our support team if you encounter this.Customer must not be under Enhanced Due DiligenceSimilarly, if a specific customer has been flagged for Enhanced Due Diligence, payouts for that customer will be blocked. Reach out to support for assistance.