Before you start

Before you proceed with Creating a PayOut deal, make sure that you have completed the following steps:

• Creating a Service account
• Issuing a JWT token
• Managing JWT tokens
• Processing transactions

How to create a PayOut deal

The Create PayOut Deal method allows you to initiate a transaction where funds are transferred from the system to a recipient's account. The deal includes parameters such as currency, client details, and recipient information.

Follow these steps to create a withdrawal (payout) deal:

1. Set up your Authorization header
   Include your Bearer token in the Authorization header: Authorization: Bearer YOUR_ACCESS_TOKEN

2. Prepare your request

   • Endpoint:

     POST https://secure.sandbox.platcore.io/deals/payout

   • Headers:

     Content-Type: application/json
     Authorization: Bearer YOUR_ACCESS_TOKEN

   • Request body parameters (required):

     • currency: ID or SYMBOL from currencies helper. Example: "USD".
     • amount: The amount to be transferred in the specified currency. Example: 1500.00.
     • currencyTo: ID or SYMBOL from currencies helper for the target currency. Example: "EUR".
     • invoiceId: Merchant reference for the invoice. Example: "INV987654".
     • clientId: Merchant reference for the client. Example: "CL987654".
     • sender_name: Name of the sender initiating the payout. Example: "John Doe".
     • recipient: Contains details of the payout recipient, including account_number, account_owner, account_iban, account_phone, type, account_bank_id, account_email, and account_ewallet_name.

   • Request body parameters (optional):

     • ttl, ttl_unit: Deal time-to-live in queue, default is 20 minutes, measured in seconds. Example: "ttl": 1200, "ttl_unit": "sec".
     • src_amount: Reference amount in the source transaction currency for cross-exchange settlement.
     • finalAmount: An optional final amount for a pre-charge rate lock.
     • baseCurrency: Base currency for deal calculation (crypto or fiat); default: "crypto".
     • fiatLiquidity: Indicates whether fiat liquidity is available.
     • feesStrategy: "add" or "sub" for how fees are handled. See this section for more detail.
     • refundAvailable: Indicates whether refunds are available for this deal.

3. Make the API call

Example request:

curl --request POST \
  --url 'https://secure.sandbox.platcore.io/deals/payout' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data '{
    "currency": "USD",
    "amount": 1500.00,
    "currencyTo": "EUR",
    "invoiceId": "INV987654",
    "clientId": "CL987654",
    "sender_name": "John Doe",
    "recipient": {
      "account_number": "DE89370400440532013000",
      "account_owner": "Jane Doe",
      "account_iban": "DE89370400440532013000",
      "account_phone": "+49123456789",
      "type": "iban",
      "account_bank_id": "123e4567-e89b-12d3-a456-426614174000",
      "account_email": "[email protected]",
      "account_ewallet_name": "Jane's eWallet"
    }
  }'

4. Example response A successful response will return a JSON object containing the deal id and status:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "new"
}

Using ADD and SUB strategies

When creating a PayOut deal, the calculation of fees can significantly impact the total amount. The feesStrategy parameter determines how fees are applied to a deal. It offers two options:

• ADD: The fee amount is added to the total transaction amount. This strategy is typically used when the customer is responsible for paying the fee.

  Example:

  • Transaction Amount: $100
  • Fee: $5
  • Total Amount (Add Strategy): 100+5 = $105

• SUB: The fee amount is deducted from the total transaction amount. This strategy is commonly used when the merchant absorbs the fee.

  • Example:
  • Transaction Amount: $100
  • Fee: $5
  • Total Amount (Sub Strategy): 100-5 = $95

❗️

Important

Ensure the correct strategy is selected to avoid discrepancies in the total transaction amount!

Recommendations

1. Validate input data: Ensure all required fields are included and correctly formatted in your request body.
2. Handle authentication: Check that your access token is valid and not expired before making the request.
3. Manage duplicate deals: Use unique invoiceId values for each deal to avoid conflicts.
4. Implement retry logic: For temporary issues, consider implementing retry logic with exponential backoff.
5. For more detail, please see the Create a Payout Deal API method description.