API ReferenceIntegrationsKnowledge Base

Amazon Payout APIs

This page contains the APIs you need to make payouts via Amazon Pay.

You can create payouts using:

Normal Payout🔗

To create a payout using the normal route you must:

  1. Create a Contact.
  2. Create a Fund Account for a contact.
  3. Create a Payout.

Create a Contact🔗

Use the below endpoint to create a contact.

/contacts

Handy Tips

  • A new contact is created if any combination of the following details is unique: name, email, contact, type and reference_id.
  • If all the above details match the details of an existing contact, the API returns details of the existing contact.
  • Use the Update Contact API if you want to make changes to an existing contact.

Know more about RazorpayX Contact API.

Request Parameters🔗

namemandatory
string The contact's name. This field is case-sensitive. A minimum of 3 characters and a maximum of 50 characters are allowed. Name cannot end with a special character, except .. Supported characters: a-z, A-Z, 0-9, space, , - , _ , / , ( , ) and , .. For example, Gaurav Kumar.
emailoptional
string The contact's email address. For example, gaurav.kumar@example.com.
contactoptional
string The contact's phone number. For example, 9123456789.
typeoptional
string Maximum 40 characters. Classification for the contact being created. For example, employee. The following classifications are available by default:
  • vendor
  • customer
  • employee
  • self

    Additional classifications:
    Additional classifications can be created via the Dashboard and then used in APIs. It is not possible to create new classifications via the API.
reference_idoptional
string Maximum 40 characters. A user-entered reference for the contact. For example, Acme Contact ID 12345.
notesoptional
object Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scotty”.

Response Parameters🔗

id
string The unique identifier linked to the contact. For example, cont_00000000000001.
entity
string The entity being created. Here, it will be contact.
name
string The contact's name. For example, Gaurav Kumar.
contact
string The contact's phone number. For example, 9123456789.
email
string The contact's email address. For example, gaurav.kumar@example.com.
type
string A classification for the contact being created. For example, employee.
reference_id
string A user-entered reference for the contact. For example, Acme Contact ID 12345.
batch_id
string This parameter is populated if the contact was created as part of a bulk upload. For example, batch_00000000000001.
active
boolean Possible values:
  • true (default) = active
  • false = inactive
notes
object Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scotty”.
created_at
integer Timestamp, in Unix, when the contact was created. For example, 1545320320.

Fund Account🔗

Use the below endpoint to create a fund account of type: wallet and provider: amazonpay.

/fund_accounts

Handy Tips

  • A new fund account is created if any combination of the following details is unique: contact_id, wallet.phone.number, wallet.phone.country_code, and wallet.email.
  • If all the above details match the details of an existing fund account, the API returns details of the existing fund account.
  • You cannot edit the details of a fund account.

Know more about RazorpayX Fund Account API.

Request Parameters🔗

contact_id mandatory

string This is the unique identifier linked to a contact. For example, cont_00000000000001.

account_type mandatory

string The account type you want to link to the contact ID. Here, it is wallet.

wallet

The contact's wallet details.

provider mandatory
string The wallet provider. Here, it is amazonpay.
phone mandatory
string Beneficiary phone details. 10 digit beneficiary phone number with the country code. For example, +919876543210 .
email optional
string Beneficiary email address. For example, gaurav.kumar@example.com.
name optional
string Wallet holder's name. Name must be between 4 - 120 characters. This field is case-sensitive. Name cannot end with a special character, except .. Supported characters: a-z, A-Z, 0-9, space, , - , _ , / , ( , ) and , .. For example, Gaurav Kumar.

Response Parameters🔗

id

string The unique identifier linked to the fund account. For example, fa_00000000000001.

entity

string Here it will be fund_account.

contact_id

string The unique identifier linked to the contact. For example, cont_00000000000001.

account_type

string The fund account type being created. Here, it will be wallet.

wallet

The contact's wallet details.

provider
string The wallet provider. Here, it is amazonpay.
phone
string 10 digit beneficiary phone number with the country code. For example, +919876543210 .
email
string Beneficiary email address. For example, gaurav.kumar@example.com.
name
string Wallet holder's name. For example, Gaurav Kumar.
active

boolean Possible values:

  • true: active
  • false: inactive
batch_id

string This parameter is populated if the fund account was created as part of a bulk upload. For example, batch_00000000000001.

created_at

integer Timestamp, in Unix, when the fund account was created. For example, 1545320320.

Payout🔗

Use the below endpoint to create a payout.

/payouts

Handy Tips
You cannot enter a custom narration when creating a payout via Amazon Pay. Contact RazorpayX support via your RazorpayX Dashboard for more information.

Know more about RazorpayX Payout API.

Request Parameters🔗

account_numbermandatory
string Your RazorpayX Virtual Account number.
Account details can be found on the RazorpayX Dashboard. For example, 7878780080316316.
Handy Tips
This is NOT your contact's bank account number.
fund_account_idmandatory
string The unique identifier linked to a fund account. For example, fa_00000000000001.
amountmandatory
integer The payout amount, in paise. For example, if you want to transfer ₹10,000, pass 1000000. Minimum value 100 (₹1). Maximum value 1000000 (₹10,000). Handy Tips
The value passed here does not include fees and tax. Fees and tax, if any, are deducted from your account balance.
currencymandatory
string The payout currency. Here, it is INR.
modemandatory
string The mode to be used to create the payout. Here it has to be amazonpay. Watch Out!
The payout mode is case sensitive. When creating payouts using APIs, ensure the payout mode is entered in upper case.
purposemandatory
string The purpose of the payout that is being created. The following classifications are available in the system by default:
  • refund
  • cashback
  • payout
  • salary
  • utility bill
  • vendor bill

    Handy Tips
    Additional purposes for payouts can be created via the Dashboard and then used in the API. However, it is not possible to create a new purpose for the payout via the API.
queue_if_low_balanceoptional
boolean Possible values:
  • true - The payout is queued when your business account does not have sufficient balance to process the payout.
  • false (default) - The payout is never queued. The payout fails if your business account does not have sufficient balance to process the payout.
reference_idoptional
string Maximum length 40 characters. A user-generated reference given to the payout. For example, Acme Transaction ID 12345. You can use this field to store your own transaction ID, if any.
notesoptional
object Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scotty”.

Response Parameters🔗

id
string The unique identifier linked to the payout. For example, pout_00000000000001.
entity
string The entity being created. Here, it will be payout.
fund_account_id
string The unique identifier linked to the fund account. For example, fa_00000000000001.
amount
integer The payout amount, in paise. Handy Tips
The value passed here does not include fees and tax. Fees and tax, if any, are deducted from your account balance.
currency
string The payout currency. Here, it is INR.
notes
object Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scotty”.
fees
integer The fees for the payout. This field is populated only when the payout moves to the processing state. For example, 5.
tax
integer The tax that is applicable for the fee being charged. This field is populated only when the payout moves to the processing state. For example, 1.
status
string The status of the payout. Possible payout states:
utr
string Here, it will be the Amazon Pay gift card ID. For example, GCID1234567.
mode
string The mode used to make the payout. Here it will be amazonpay.
purpose
string The purpose of the payout that is being created. The following classifications are available in the system by default:
  • refund
  • cashback
  • payout
  • salary
  • utility bill
  • vendor bill

    Handy Tips
    Additional purposes for payouts can be created via the Dashboard and then used in the API. However, it is not possible to create a new purpose for the payout via the API.
reference_id
string Maximum length 40 characters. A user-generated reference given to the payout. For example, Acme Transaction ID 12345. You can use this field to store your own transaction ID, if any.
narration
string Defaults to the Merchant Billing Label. You cannot enter a custom narration when creating a payout via Amazon Pay. Contact RazorpayX support for more information.
batch_id
string This parameter is populated if the contact was created as part of a bulk upload. For example, batch_00000000000001.
failure_reason
string The reason for the payout failing.
created_at
integer Timestamp, in Unix, when the contact was created. For example, 1545320320.

Composite Payout API🔗

The composite API allows you to make a payout using a single API call. This reduces the number of calls you would otherwise need to make to create a payout. The composite API also gives you the flexibility to either create a new contact and fund account or use existing contact and fund account details (contact_id and fund_account_id) to make a payout.

Use the below endpoint to create a payout via Amazon Pay.

/payouts

Handy Tips

  • Contact
    • A new contact is created if any combination of the following details is unique: fund_account.contact.name, fund_account.contact.email, fund_account.contact.contact, fund_account.contact.type and fund_account.contact.reference_id.
    • If all the above details match the details of an existing contact, the API returns details of the existing contact.
    • Use the Update Contact API if you want to make changes to an existing contact.
  • Fund Account
    • A new fund account is created if any combination of the following details is unique: fund_account.wallet.name, fund_account.wallet.email, fund_account.wallet.phone.number, fund_account.wallet.phone.country_code, fund_account.contact.name, fund_account.contact.email, fund_account.contact.contact, fund_account.contact.type and fund_account.contact.reference_id.
    • If all the above details match the details of an existing fund account, the API returns details of the existing fund account.
    • You cannot edit the details of a fund account.

Know more about RazorpayX Composite API.

Request Parameters🔗

account_numbermandatory

string Your RazorpayX Virtual Account number.
Account details can be found on the RazorpayX Dashboard. For example, 7878780080316316.
Handy Tips
This is NOT your contact's bank account number.

amountmandatory

integer The payout amount, in paise. For example, if you want to transfer ₹10,000, pass 1000000. Minimum value is 100 (₹1). Maximum value 1000000 (₹10,000). Handy Tips
The value passed here does not include fees and tax. Fees and tax, if any, are deducted from your account balance.

currencymandatory

string The payout currency. Here, it is INR.

modemandatory

string The mode to be used to create the payout. Here, it has to be amazonpay.
Watch Out!
The payout modes are case sensitive. When creating payouts using APIs, ensure payout modes are entered in upper case.

purposemandatory

string The purpose of the payout. Classifications available in the system by default:

  • refund
  • cashback
  • payout
  • salary
  • utility bill
  • vendor bill

    Handy Tips
    Additional purposes for payouts can be created via the Dashboard and then used in the API. However, it is not possible to create a new purpose for the payout via the API.
fund_account

Details of the contact and fund account to which the payout should be made.

account_typemandatory

string The type of account to be linked to the contact id. Here, the value has to be wallet.

wallet

The contact's wallet details.

provider mandatory
string The wallet provider. Here, it is amazonpay.
phone mandatory
string 10 digit beneficiary phone number with the country code. For example, +919876543210.
email optional
string Beneficiary email address. For example, gaurav.kumar@example.com.
name optional
string Wallet holder's name. Between 4 and 120 characters. This field is case sensitive. Supported characters: a-z, A-Z, 0-9, space, , - , _ , / , ( , ) and , .. For example, Gaurav Kumar.
contact

Details of the contact to whom the payout should be made.

namemandatory
string Contact's name. Minimum 3 characters. Maximum 50 characters. This field is case sensitive. Supported characters: a-z, A-Z, 0-9, space, , - , _ , / , ( , ) and , .. For example, Gaurav Kumar.
emailoptional
string The contact's email address. For example, gaurav.kumar@example.com.
contactoptional
string The contact's phone number. For example, 9123456789.
typeoptional
string Classification for the contact. For example, employee. Classifications are available by default:
  • vendor
  • customer
  • employee
  • self

    Additional classifications:
    Additional classifications can be created via the Dashboard and then used in APIs. It is not possible to create new classifications via the API.
reference_idoptional
string Maximum length 40 characters. A reference you enter for the contact. For example, Acme Contact ID 12345.
notesoptional
object Notes you can enter for the contact for future reference. This is a key-value pair. For example, "note_key": "Beam me up Scotty".
queue_if_low_balanceoptional

boolean Possible values:

  • true - The payout is queued when your business account does not have sufficient balance to process the payout.
  • false (default) - The payout is never queued. The payout fails if your business account does not have sufficient balance to process the payout.
reference_idoptional

string Maximum length 40 characters. A reference you enter for the payout. For example, Acme Transaction ID 12345. You can use this field to store your own transaction ID, if any.

narrationoptional

string Maximum length 30 characters. Allowed characters: a-z, A-Z, 0-9 and space. This is a custom note that also appears on the bank statement.

Handy Tips
● If no value is passed for this parameter, it defaults to the Merchant Billing Label.
● Ensure that the most important text forms the first 9 characters as banks may truncate the rest as per their standards.

notesoptional

object Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scotty”.

Response Parameters🔗

id

string The unique identifier linked to the payout. For example, pout_00000000000001.

entity

string The entity being created. Here, it will be payout.

fund_account_id

string The unique identifier linked to the fund account. For example, fa_00000000000001.

fund_account

Contact and fund account details to which the payout was made.

id

string The unique identifier linked to the fund account. For example, fa_00000000000001.

entity

string Here it will be fund_account.

contact_id

string The unique identifier linked to the contact. For example, cont_00000000000001.

contact

Details of the contact to whom the payout is being made.

id
string The unique identifier linked to the contact. For example, cont_00000000000001.
entity
string The entity being created. Here, it will be contact.
name
string The contact's name. For example, Gaurav Kumar.
contact
string The contact's phone number. For example, +919123456789.
email
string The contact's email address. For example, gaurav.kumar@example.com.
type
string Classification for the contact being created. For example, employee. Classifications are available by default:
  • vendor
  • customer
  • employee
  • self

    Additional classifications:
    Additional classifications can be created via the Dashboard and then used in APIs. It is not possible to create new classifications via the API.
reference_id
string A reference you entered for the contact. For example, Acme Contact ID 12345.
batch_id
string This parameter is populated if the contact was created as part of a bulk upload. For example, batch_00000000000001.
active
boolean Possible values:
  • true: active
  • false: inactive
notes
object User-entered notes for internal reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. For example, "note_key": "Beam me up Scotty”.
created_at
integer Timestamp, in Unix, when the contact was created. For example, 1545320320.
account_type

string The type of account to be linked to the contact ID. Here, the value has to be wallet.

wallet

The contact's wallet details.

provider
string The wallet provider. Here it is amazonpay.
phone
string 10 digit beneficiary phone number with the country code. For example, +919876543210.
email
string Beneficiary email address. For example, gaurav.kumar@example.com.
name
string Wallet holder's name. Between 4 and 120 characters. For example,Gaurav Kumar.
active

boolean Possible values:

  • true: active
  • false: inactive
batch_id

string This parameter is populated if the fund account was created as part of a bulk upload. For example, batch_00000000000001.

created_at

integer Timestamp, in Unix, when the fund account was created. For example, 1545320320.

amount

integer The payout amount, in paise.
Handy Tips:
The value passed here does not include fees and tax. Fees and taxes, if any, are deducted from your account balance.

currency

string The payout currency. Here, it is INR.

notes

object User-entered notes for internal reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. For example, "note_key": "Beam me up Scotty”.

fees

integer The fees for the payout in paise. This field is populated only when the payout moves to the processing state. For example, 5.

tax

integer The tax that is applicable for the fee being charged in paise. This field is populated only when the payout moves to the processing state. For example, 1.

status

string The payout status. Possible payout states:

purpose

string The purpose of the payout. Classifications available by default:

  • refund
  • cashback
  • payout
  • salary
  • utility bill
  • vendor bill

    Handy Tips
    Additional purposes for payouts can be created via the Dashboard and then used in the API. However, it is not possible to create a new purpose for the payout via the API.
utr

string Here, it will be the Amazon Pay gift card ID. For example, GCID1234567.

mode

string The mode used to make the payout. Here, it will be amazonpay.

reference_id

string A reference you entered for the payout. For example, Acme Transaction ID 12345. You can use this field to store your own transaction ID, if any.

narration

string This is a custom note that also appears on the bank statement.

If no value is passed for this parameter, it defaults to the Merchant Billing Label.

batch_id

string This parameter is populated if the contact was created as part of a bulk upload. For example, batch_00000000000001.

failure_reason

string The reason for the payout failing.

created_at

integer Timestamp, in Unix, at which the payout was created. For example, 1545320320.

Payout Idempotency🔗

Idempotency allows you to safely retry or send the same request multiple times without fear of performing the same action more than once.

Know more about RazorpayX APIs.

Improve Payout Processing Time🔗

We recommend that you create the contact and fund account before making a payout. Doing this helps you improve payout processing time.

You can continue to use the contact and fund account details (instead of IDs) in the composite API to make payouts. Doing this will not create duplicate contacts or fund accounts in your system.

×