Create Payout Transaction

Create Payout Transaction

Execute a payout by providing beneficiary details along with a valid quotation. This endpoint debits your account and initiates the transfer to the recipient through the selected payer network.

---

Overview

The transaction endpoint:

• Uses a previously created quotation for locked rates
• Validates all beneficiary and sender KYC data
• Initiates the money transfer through the payer network
• Returns transaction details for tracking
• Sends webhook notifications for status updates

Prerequisites:

1. Create a quotation using Create Quotation
2. Ensure sufficient balance in your account
3. Have all beneficiary details ready

---

Endpoint

POST /api/v1/pay-out/transaction

Authentication: Basic Auth (Business Key + Business Secret)

Base URLs:

• Sandbox: https://sandbox-api.cashela.com
• Production: https://api.cashela.com

---

Required Headers

Authorization: Basic <base64_encoded_credentials>
Content-Type: application/json
Accept: application/json
Idempotency-Key: <uuid-v4>

---

Request Parameters

Body Parameters

Parameter	Type	Required	Description
quotation_id	string	Yes	Quotation ID from Create Quotation. Must not be expired.
payer_id	integer	Yes	Payer/bank ID from quotation’s payers_available array or Get Payers.
external_identifier	string	Yes	Your unique reference for this transaction. Used for idempotency and reconciliation. Max 255 characters.
credit_party_identifier	object	Yes	Beneficiary bank/account details. Required fields vary by payer.
sender	object	Yes	Sender (originator) KYC information.
beneficiary	object	Yes	Beneficiary (recipient) KYC information.
purpose_of_remittance	string	Yes	Standardized reason for transfer. See Purpose Codes.
callback_url	string	Yes	HTTPS webhook URL for transaction status updates.

Credit Party Identifier (Bank Account Details)

Field	Type	Required	Description
bank_account_number	string	Yes	Beneficiary’s bank account number.
branch_number	string	Conditional	Bank branch/routing code. Required for some countries.
bank_account_type	string	Conditional	Account type: CHECKING, SAVINGS. Required for some countries.
swift_code	string	Conditional	SWIFT/BIC code for international transfers.
iban	string	Conditional	IBAN for European transfers.

Sender Object (Originator KYC)

Field	Type	Required	Description
first_name	string	Yes	Sender’s legal first name.
last_name	string	Yes	Sender’s legal last name.
code	string	Yes	Sender’s ID document number.
date_of_birth	string	Yes	Date of birth in YYYY-MM-DD format.
address	string	Yes	Full address including city and state.
country_id	string	Yes	ISO 3-letter country code (e.g., USA).
email	string	Yes	Valid email address.
msisdn	string	Yes	Phone number in E.164 format (e.g., +1234567890).

Beneficiary Object (Recipient KYC)

Field	Type	Required	Description
first_name	string	Yes	Beneficiary’s legal first name.
last_name	string	Yes	Beneficiary’s legal last name.
document_number	string	Yes	Beneficiary’s ID document number.
country_id	string	Yes	ISO 3-letter country code (e.g., BRA).
email	string	Conditional	Email address. Required for some corridors.
msisdn	string	Conditional	Phone number in E.164 format. Required for some corridors.
bank_id	string	Conditional	Bank identifier code. Required for some countries.

Purpose Codes

Use one of the following standardized purpose codes:

Code	Description
FAMILY_SUPPORT	Family maintenance/support
EDUCATION	Education expenses
MEDICAL	Medical expenses
TRAVEL	Travel expenses
SAVINGS	Personal savings
SALARY	Salary payment
GOODS_SERVICES	Payment for goods or services
INVESTMENT	Investment purposes
LOAN_REPAYMENT	Loan repayment
OTHER	Other purposes

---

Example Request

curl -X POST "https://api.cashela.com/api/v1/pay-out/transaction" \
  -H "Authorization: Basic $(echo -n 'your_business_key:your_business_secret' | base64)" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: c3d4e5f6-a7b8-9012-cdef-34567890abcd" \
  -d '{
    "quotation_id": "qtn_01HJ3KBCD8E9F0G1H2I3J4K5L6",
    "payer_id": 45,
    "external_identifier": "PAYOUT-2025-00123",
    "credit_party_identifier": {
      "bank_account_number": "01236523256333349",
      "branch_number": "0001",
      "bank_account_type": "CHECKING"
    },
    "sender": {
      "first_name": "John",
      "last_name": "Doe",
      "code": "ID123456789",
      "date_of_birth": "1980-01-15",
      "address": "123 Main Street, New York, NY 10001",
      "country_id": "USA",
      "email": "john.doe@example.com",
      "msisdn": "+12125551234"
    },
    "beneficiary": {
      "first_name": "Maria",
      "last_name": "Silva",
      "document_number": "12345678901",
      "country_id": "BRA",
      "email": "maria.silva@example.com",
      "msisdn": "+5511999999999",
      "bank_id": "033"
    },
    "purpose_of_remittance": "FAMILY_SUPPORT",
    "callback_url": "https://yourdomain.com/webhooks/payout"
  }'

---

Response Format

Success Response (201 Created)

{
  "success": true,
  "data": {
    "id": "payout_01HJ3KBCD8E9F0G1H2I3J4K5L6",
    "reference": "CSH-PAYOUT-20250202-00001234",
    "external_identifier": "PAYOUT-2025-00123",
    "status": "PROCESSING",
    "status_message": "Transaction submitted for processing",
    "quotation_id": "qtn_01HJ3KBCD8E9F0G1H2I3J4K5L6",
    "source": {
      "amount": 1000.00,
      "currency": "USD",
      "country": "USA"
    },
    "destination": {
      "amount": 5416.96,
      "currency": "BRL",
      "country": "BRA"
    },
    "payer": {
      "id": 45,
      "name": "BANCO SANTANDER BRASIL S.A",
      "code": "santander_br",
      "currency": "BRL",
      "country": "BRA"
    },
    "fee": {
      "amount": 15.00,
      "currency": "USD"
    },
    "fx_rate": 5.41696,
    "sender": {
      "first_name": "John",
      "last_name": "Doe",
      "country_id": "USA"
    },
    "beneficiary": {
      "first_name": "Maria",
      "last_name": "Silva",
      "country_id": "BRA"
    },
    "purpose_of_remittance": "FAMILY_SUPPORT",
    "estimated_delivery": "2025-02-03T18:00:00Z",
    "created_at": "2025-02-02T12:56:04.000Z",
    "updated_at": "2025-02-02T12:56:04.000Z"
  },
  "message": "Payout transaction created successfully"
}

---

Response Parameters

Field	Type	Description
id	string	Unique Cashela transaction ID. Use for tracking and support.
reference	string	Cashela reference number for reconciliation.
external_identifier	string	Your transaction reference echoed back.
status	string	Current transaction status. See Transaction Statuses.
status_message	string	Human-readable status description.
quotation_id	string	ID of the quotation used for this transaction.
source	object	Source amount, currency, and country.
destination	object	Destination amount, currency, and country.
payer	object	Payer/provider details used for this transfer.
fee	object	Transaction fee charged.
fx_rate	number	Exchange rate applied.
sender	object	Sender details (abbreviated).
beneficiary	object	Beneficiary details (abbreviated).
purpose_of_remittance	string	Purpose code submitted.
estimated_delivery	string	ISO 8601 timestamp of expected delivery.
created_at	string	ISO 8601 timestamp of transaction creation.
updated_at	string	ISO 8601 timestamp of last status update.

---

Transaction Statuses

Status	Description	Webhook Event
PENDING	Transaction created, awaiting processing	payout.created
PROCESSING	Transaction being processed by payer	payout.processing
SUBMITTED	Transaction submitted to payer network	payout.submitted
COMPLETED	Funds delivered to beneficiary	payout.completed
FAILED	Transaction failed	payout.failed
CANCELLED	Transaction cancelled	payout.cancelled
REFUNDED	Funds returned to your account	payout.refunded

---

Webhook Events

Your callback_url receives real-time status updates:

{
  "id": "evt_01HJ3KBCD8E9F0G1H2I3J4K5L6",
  "type": "payout.completed",
  "created_at": "2025-02-03T15:30:00Z",
  "data": {
    "object": {
      "id": "payout_01HJ3KBCD8E9F0G1H2I3J4K5L6",
      "external_identifier": "PAYOUT-2025-00123",
      "status": "COMPLETED",
      "reference": "CSH-PAYOUT-20250202-00001234",
      "destination": {
        "amount": 5416.96,
        "currency": "BRL"
      },
      "completed_at": "2025-02-03T15:30:00Z"
    }
  }
}

---

Error Responses

HTTP Status	Error Code	Description
400	INVALID_INPUT	Malformed request or invalid JSON
401	UNAUTHORIZED	Invalid API credentials
403	FORBIDDEN	IP not allowlisted
403	INSUFFICIENT_FUNDS	Account balance too low
404	QUOTATION_NOT_FOUND	Invalid or expired quotation_id
404	PAYER_NOT_FOUND	Invalid payer_id
409	IDEMPOTENCY_CONFLICT	Same key used with different request
409	QUOTATION_ALREADY_USED	Quotation already used for another transaction
422	QUOTATION_EXPIRED	Quotation rate lock has expired
422	VALIDATION_ERROR	KYC or field validation failed
422	COMPLIANCE_HOLD	Transaction held for compliance review
429	RATE_LIMITED	Too many requests

---

Best Practices

1. Always use a valid quotation – Create a quotation immediately before the transaction to ensure the rate is current
2. Validate beneficiary details – Ensure all bank account details are correct before submission
3. Handle all status transitions – Implement webhook handlers for all status types
4. Store transaction IDs – Keep both your external_identifier and Cashela’s id for reconciliation
5. Implement retry logic – Use exponential backoff for transient errors
6. Test in sandbox – Verify all flows work correctly before production

---

Related Documentation

• Create Quotation – Generate FX quote before transaction
• Get Payers – Query available payer networks
• Get Countries – View supported destinations
• Get Services – Query payout services
• Error Handling – Complete error reference
• Webhook Security – Signature verification