Money Transfer - CashQ API Documentation

Money Transfer

curl --request POST \
  --url https://api.example.com/api/transfer \
  --header 'API-KEY: <api-key>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "id": "<string>",
  "sender_phone": "<string>",
  "receiver_phone": "<string>",
  "amount": "<string>",
  "service": "<string>",
  "receiver_country": "<string>",
  "receiver_currency": "<string>",
  "attribute": [
    {}
  ]
}
'

{
  "payment_response": {
    "payment_id": null,
    "state": "-2",
    "substate": "0",
    "code": "0",
    "id": "123456789"
  },
  "error": "",
  "success": true
}

POST

api

transfer

Money Transfer

curl --request POST \
  --url https://api.example.com/api/transfer \
  --header 'API-KEY: <api-key>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "id": "<string>",
  "sender_phone": "<string>",
  "receiver_phone": "<string>",
  "amount": "<string>",
  "service": "<string>",
  "receiver_country": "<string>",
  "receiver_currency": "<string>",
  "attribute": [
    {}
  ]
}
'

{
  "payment_response": {
    "payment_id": null,
    "state": "-2",
    "substate": "0",
    "code": "0",
    "id": "123456789"
  },
  "error": "",
  "success": true
}

Overview

Execute a money transfer from your merchant account to any phone number in supported countries. This endpoint processes the actual transfer and debits your account.

Important: Always call Check Transfer before executing a transfer to validate parameters and check receiver status.

Endpoint

POST /api/transfer

Authentication

API-KEY

string

required

Your CashQ API Key for authentication

Content-Type

string

required

Must be application/json

Request Body

The request body parameters are identical to Check Transfer.

string

required

Unique numeric identifier for this transfer. Should match the ID used in Check Transfer. Must be numeric only.

sender_phone

string

required

Sender’s phone number in E.164 format (e.g., "+15615019469")

receiver_phone

string

required

Receiver’s phone number in E.164 format (e.g., "+201234567890")

amount

string

required

Transfer amount in dollars (e.g., "5.0" for $5.00)

service

string

required

ID of corridor (e.g., "1271" for EGP). Payment attributes depend on the corridor and will be provided for the requested corridor upon request.

receiver_country

string

required

Country code of receiver (e.g., "MX" for Mexico, "EG" for Egypt).

receiver_currency

string

required

Currency code for the receiver (e.g., "MXN" for Mexican Peso, "EGP" for Egyptian Pound)

attribute

array

required

Array of corridor-specific payment attributes. Required attributes vary by corridor and include receiver details, bank information, address, and identification. Contact support for specific corridor requirements.

Show Attribute structure

Each attribute object contains:

name (string): Attribute name
value (string): Attribute value

Common attributes:

receivedAmount - Amount in receiver’s currency (e.g., amount in EGP)
receiverName - Full name of receiver
receiverFirstName - Receiver’s first name
receiverLastName - Receiver’s last name
receiverAddressStreet - Street address
receiverAddressCity - City
receiverAddressState - State/Region
receiverAddressCountry - Country code (e.g., “EG”)
receiverAccType - Account type (e.g., “1” for bank account)
receiverIssuerCode - Bank issuer code
receiverAccountNumber - Bank account number
receiverBankBranchCode - Bank branch code (optional, if applicable)
receiverBankName - Bank name
receiverIdType - ID type (“2” for International Passport, “3” for Identification ID)
receiverIdNumber - Identification number

Important: approvelyId AttributeIf you’re using the Payout API with our Payin API, you must include the approvelyId attribute to link the payout with the payin transaction:

{
  "name": "approvelyId",
  "value": "46364493"
}

Without this attribute, the transaction will be created but will wait for automated/manual reconciliation checking, which may cause delays.

Request Example

curl -X POST 'https://api.cashqbot.com/api/transfer' \
  -H 'API-KEY: your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "123456789",
    "sender_phone": "+15551234567",
    "receiver_phone": "+525551234568",
    "amount": "5.0",
    "service": "1234",
    "receiver_country": "MX",
    "receiver_currency": "MXN",
    "attribute": []
  }'

Response

success

boolean

required

Indicates if the transfer was initiated successfully

error

string

Error message if transfer failed, empty string if successful

payment_response

object

Transfer response details

Show Payment response properties

string

The transfer ID you provided

payment_id

string | null

Internal payment ID (may be null initially)

state

string

Transfer state code (see Status Codes)

substate

string

Transfer substate code

code

string

Response code

Response Examples

{
  "payment_response": {
    "payment_id": null,
    "state": "-2",
    "substate": "0",
    "code": "0",
    "id": "123456789"
  },
  "error": "",
  "success": true
}

Complete Transfer Flow

Follow this recommended flow for executing transfers:

Check balance

Verify you have sufficient funds using Get Balance

const balance = await getBalance();
if (balance.balance + balance.overdraft < amountInCents) {
  throw new Error('Insufficient funds');
}

Check KYC

Verify receiver’s KYC status using Check KYC

const kyc = await checkKYC(receiverPhone);
if (parseFloat(kyc.money_limit) < amount) {
  throw new Error('Amount exceeds receiver limit');
}

Validate transfer

Call Check Transfer to validate parameters

const validation = await checkTransfer(transferData);
if (!validation.success) {
  throw new Error('Validation failed');
}

Execute transfer

Call this endpoint to execute the transfer

const result = await executeTransfer(transferData);

Monitor status

Use Check Status to monitor transfer completion

const status = await pollTransferStatus(transferId);

Transfer States

After initiating a transfer, monitor its status:

State	Description	Action
0	New	Transfer created, processing starting
40	Processing	Transfer in progress
60	Success	Transfer completed successfully
80	Error	Transfer failed
-2	Not Found	Transfer ID not found

See the complete Status Codes Reference for all possible states.

Error Responses

Error Code	Description	Solution
`authentication_error`	Invalid or missing API key	Verify your API key
`insufficient_funds`	Not enough balance	Add funds or reduce amount
`invalid_phone_number`	Phone number format incorrect	Use E.164 format without `+`
`invalid_amount`	Amount is invalid	Check amount is positive and formatted correctly
`kyc_not_verified`	Receiver KYC limits exceeded	Reduce amount or ask receiver to verify
`duplicate_transfer`	Transfer ID already used	Use a unique transfer ID
`internal_server_error`	Server error occurred	Retry the request

Best Practices

Always validate first

Call Check Transfer before executing to catch errors early and check receiver status.

Use unique transfer IDs

Generate unique IDs for each transfer. Reusing IDs may cause duplicate transfer errors.

Check balance before transfer

Verify sufficient funds to avoid insufficient balance errors.

Monitor transfer status

Poll the status endpoint to track transfer completion and handle any issues.

Handle payment invitations

Inform users when sending to new receivers about the 6-hour expiration window.

Implement idempotency

Store transfer IDs and results to prevent duplicate transfers if requests are retried.

Log all transfers

Keep detailed logs of all transfer attempts for debugging and reconciliation.

Check Transfer

Validate transfer before execution

Check Status

Monitor transfer status after execution

Get Balance

Check available funds before transfer

Check KYC

Verify receiver’s limits before transfer

Check Transfer Status Codes Reference

​Overview

​Endpoint

​Authentication

​Request Body

​Request Example

​Response

​Response Examples

​Complete Transfer Flow

​Transfer States

​Error Responses

​Best Practices

​Related Endpoints

Check Transfer

Check Status

Get Balance

Check KYC

Overview

Endpoint

Authentication

Request Body

Request Example

Response

Response Examples

Complete Transfer Flow

Transfer States

Error Responses

Best Practices

Related Endpoints