POSTAdd Recipient

Add a new beneficiary, or update an existing one, under a DMT-Levin sender.

POST/customer/payment/dmt-levin/sender/{customer_id}/recipient

Warning

The UAT environment is not available for this API — requests to https://staging.eko.in/ekoapi/v3 return an error response. Test it in Production.

Adds a new recipient or updates an existing recipient for the sender. Provide the recipient's name, mobile, bank account, IFSC and Eko bank_id (resolve it from the IFSC with Get IFSC Details). On success a recipient_id is returned — use it to send money. A sender can add a maximum of 5 recipients in a day.

Request

Path parameters

Field	Type	Required	Description
`customer_id`	string	required	Sender's 10-digit mobile number.e.g. 9999999999

customer_idstringRequired

Sender's 10-digit mobile number.

example: 9999999999

Body parameters

Field	Type	Required	Description
`initiator_id`	string	required	Registered mobile number of the API user (see Platform Credentials).e.g. 9962981729
`client_ref_id`	string	optional	Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.e.g. 2026010100123456789
`user_code`	string	required	User code value of the retailer from whom the request is coming.e.g. 99080253
`bank_id`	integer	required	Eko's unique ID for the recipient's bank. Resolve it from the IFSC with Get IFSC Details.e.g. 6
`recipient_name`	string	required	Full name of the recipient.e.g. Rahul
`recipient_mobile`	string	required	Recipient's valid 10-digit mobile number.e.g. 8888888888
`recipient_type`	integer	required	Recipient type. Value will be 3.e.g. 3
`account`	string	optional	Recipient's bank account number used for receiving funds.e.g. 1234567891023
`ifsc`	string	optional	IFSC code of the recipient's bank branch.e.g. HDFC0000583
`account_type`	integer	required	Account type. Defaults to 1.e.g. 1
`type`	string	required	Recipient identifier type. Defaults to `ifsc`.e.g. ifsc

initiator_idstringRequired

Registered mobile number of the API user (see Platform Credentials).

example: 9962981729

client_ref_idstringoptional

Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.

example: 2026010100123456789

user_codestringRequired

User code value of the retailer from whom the request is coming.

example: 99080253

bank_idintegerRequired

Eko's unique ID for the recipient's bank. Resolve it from the IFSC with Get IFSC Details.

example: 6

recipient_namestringRequired

Full name of the recipient.

example: Rahul

recipient_mobilestringRequired

Recipient's valid 10-digit mobile number.

example: 8888888888

recipient_typeintegerRequired

Recipient type. Value will be 3.

example: 3

accountstringoptional

Recipient's bank account number used for receiving funds.

example: 1234567891023

ifscstringoptional

IFSC code of the recipient's bank branch.

example: HDFC0000583

account_typeintegerRequired

Account type. Defaults to 1.

example: 1

typestringRequired

Recipient identifier type. Defaults to `ifsc`.

example: ifsc

These headers authenticate and sign every request. See How Auth Works for details.

Field	Type	Required	Description
`developer_key`	string	required	Static API key issued to your account after KYC.
`secret-key`	string	required	Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).
`secret-key-timestamp`	string	required	Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.
`content-type`	string	required	application/jsone.g. application/json

developer_keystringRequired

Static API key issued to your account after KYC.

secret-keystringRequired

Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).

secret-key-timestampstringRequired

Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.

content-typestringRequired

application/json

example: application/json

Response types

response_type_id	Meaning	Next step
`43`	Recipient added — proceed to Send Transaction OTP	Send Transaction OTP

Responses

43Recipient added — proceed to Send Transaction OTPNext:Send Transaction OTP

statusnumber
Primary success indicator (0 = success).
messagestring
Human-readable response / error message.
response_status_idnumber
UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.
response_type_idnumber
A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.
dataobject
API-specific response payload.
- recipient_idnumber
  Unique recipient identifier — use it to send money.
- customer_idstring
  Sender's mobile number (echoed back).
- recipient_mobilestring
  Recipient mobile number (echoed back).
- initiator_idstring
  Partner initiator ID (echoed back).
- pipesobject
  Available settlement pipes for the new recipient.