Skip to main content

Global Payouts API

Overview​

Create a payout transaction to a selected Channel on behalf of a given customer by settling in your chosen CryptoCurrency and providing the Dynamic Form data required to complete the transaction. Payout transactions, by default, are settled from the reserve balance held in your NOAH crypto account - where cryptocurrencies are network agnostic. For more details on this product, see the Global Payouts API Product page.

Prerequisites​

1. Register Your Interest​

  1. Register your interest or book a demo by contacting us on business@noah.com.
  2. Signup for a Sandbox account and contact us to upgrade it to a business account.

2. Authentication & Request Signing​

For guidance on generating and configuring your API keys, see the Authentication page.

  1. Generate your Sandbox API key via the Business Dashboard.
  2. Include your API key in the X-Api-Key header of all requests.
  3. Request Signing is optional in Sandbox and required in Production. It is important to setup Request Signing before migrating to Production, to do this see the Request Signing page.

3. Webhook Configuration​

For guidance on webhook subscriptions and configuration, see the Configuration page.

  1. Optionally whitelist NOAH's Webhook IP addresses, detailed on the Whitelisting section.
  2. Create a webhook subscription for the following event type, the details required to ingest the webhooks are also available on the respective page.

Throughout the execution of a payout, you will receive one type of webhook, in two cases:

  1. Transaction - to notify you when the transaction has been created - this will begin with the Pending status.
  2. Transaction - to notify you when the transaction's status has changed to any of: Pending, Settled or Failed.

Execution Steps​

1. Create a Customer​

When integrating under the Reliance Model, you must ensure that any customer executing a transaction has a valid and complete KYC Status in your system.

  • Create a customer, if not already created, via the Customers endpoint.
  • Ensure your CustomerID is stored against the compliance profile of the same customer, to reference when creating transactions.

2. Define the Payout Channel​

  1. Retrieve the list of available countries by calling the Supported Countries endpoint.
  2. Determine the FiatCurrency as an ISO 4217 currency code.
  3. Retrieve a list of compatible channels by calling the Supported Channels endpoint, providing your settlement CryptoCurrency, FiatCurrency and Country.

3. Render or Populate the Dynamic Form​

  1. Call the Dynamic Form endpoint with the selected ChannelID to retrieve the FormSchema.
  2. Render the FormSchema on your interface to collect input from your customers, or populate the required fields from pre-existing data.

4. Prepare the Transaction​

The prepare endpoint provides the most accurate and up-to-date pricing estimate and pre-validates any form data supplied, working with an existing PaymentMethodID if available. If called without an existing PaymentMethodID, all necessary fields will be requested; otherwise, only the missing fields will be requested.

On a successful call to the Prepare endpoint, you will receive a FormSessionID which can be used to submit the transaction.

  1. Retrieve your ChannelID, PaymentMethodID, CryptoCurrency, CustomerID, FiatAmount and Form fields, from the previous steps.
  2. Call the Prepare Sell Transaction endpoint.
  3. If you are directly settling with a customer, debit the customer's account in your system - using the FiatAmount as a reference for absorbing or passing on the fees to your customer.

You can fetch a customer's existing payment methods using the Payment Methods endpoint.

5. Submit the Transaction​

  1. Submit a POST request to the Create Sell Transaction endpoint with the FormSessionID retrieved from the previous step and the required transaction details. You will receive a response including the Transaction object.
  2. When the transaction is created, your account's AvailableBalance will be immediately reduced and we will attempt to complete the transaction at the best available price. If this is not possible due to price fluctuations, we will cancel the transaction and refund your AvailableBalance. If the transaction is successful, during settlement we will reduce your TotalBalance by the final amount and adjust your AvailableBalance to account for any difference between the final, settled amount and the initial CryptoAuthorizedAmount.
  3. When the transaction status changes, you will receive a Transaction event webhook to your subscription URL.

Prepare Endpoints and PaymentMethodIDs​

The prepare endpoint's primary purposes are:

  • To get the most accurate and up-to-date pricing estimate.
  • To pre-validate any form data you have supplied, which works in conjunction with an existing PaymentMethodID.

If you call the forms endpoint without an existing PaymentMethodID, it will request the entire set of fields we need to collect as new data for instructing a payment to that channel.

If you call the forms endpoint with an existing PaymentMethodID, it will request only the fields that we don't yet have data for. For example, let's say a Customer has already made an offramp on ChannelA. If they later come back to make another one, and you supply a valid PaymentMethodID, in the forms response, we will not request data that we already have.

For a Customer's first transaction, they won't have any saved Payment Methods so you won't have a PaymentMethodID - it's an optional field.