88mids

Payout API

Payout Request Table

Field NameData DescriptionTypeMinMaxExampleRequired
accountBeneficiary AccountCH1–abc123yes
amountFloat data type. Decimals are ignored: 100.99 is paid out as 100. Accepted as a number or a numeric string, e.g. 500 or "500".NU1–50000.00yes
currencyAlphabetic currency code, e.g. INRCH33PKRyes
callbackUrlUrl where payment callback will be sentURL––https://example.com/callbackyes
countryISO 3166-1-alpha-2CH22PKyes
emailCustomer’s emailAN6120name@email.comyes
dataFor additional parameters for payoutOBJ––data{
"name":"John Doe"
}		yes
hashPayout payload signature.
Contact your account manager
to enable this parameter.
When enabled, a payout
without it is rejected. More		AN6464F74723256…..E9EF2yes
(if enabled)
methodMethods supported.CH––BANK_TRANSFERyes
orderIdMerchant Order IDAN150abc123456yes
ipCustomer’s IPIP––192.0.2.1yes

A payout request with an orderId that has already been used is rejected.

Generic Payout Request Body & Response Sample

Request Body for Payouts

{
  "account": "5466547856436481364252",
  "amount": "10000",
  "country": "AR",
  "currency": "ARS",
  "email": "email@test.com",
  "ip": "192.0.2.1",
  "method": "BANK_TRANSFER",
  "orderId": "abc123456",
  "callbackUrl": "https://example.com/callback",
  "data": {}
}

Generic Payout Response Sample

{
  "status": "PENDING",
  "message": "Transaction is being processed",
  "id": "912z-1zs4-acvb-1bre3",
  "orderId": "abc123456"
}
Payout Request Optional Data Field Table:

The payout request “data” field contains possible additional parameters, which are provider dependent. If the parameters are missing, the required values will be asked (via web form) from the customer.

Field NameData DescriptionTypeMinMaxExample
ifscBeneficiary ifsc numberCH1111BSBN0001234
accountNameBeneficiary nameCH1–Johny Cash
bankCodeBeneficiary bank codeCH1–BSBN0001111
bankNameBeneficiary bankCH1–BSBN Bank
bankBranchBeneficiary bank branchCH1–BB
bankAddressBeneficiary bank addressCH1–BA
bankCityBeneficiary bank cityCH1–Bank Area
bankStateBeneficiary bank stateCH1–Bank Province
bsbAustralian beneficiary bank codeNU66123456
dobCustomer’s Date of BirthAN10101990-12-21
nameBeneficiary first nameCH1–Johny
lastNameBeneficiary last nameCH1–Cash
streetBeneficiary street addressCH1–122 Grenfell St
cityBeneficiary cityCH1–Adelaide
stateBeneficiary stateCH1–SA
postalCodeBeneficiary postal codeCH1–5000
mobileNumberBeneficiary mobile numberCH1–5467756764
pinMerchant’s own customer identifier, e.g. a user IDCH1–user_1
cuitBeneficiary CUIT (Argentine tax identification number)CH1–76576574758
tinTax Identification NumberNU91112345678910
tinDateTax Identification Number DateAN10102021-12-21
Payout API Response Fields
DescriptionFormatExplanation
idStringSystem Transaction ID
messageStringPayment response message
statusStringTransaction status
orderIdStringMerchant Order ID

Payout Request Hash Generation

To ensure the integrity and security of payout requests, the hash value must be generated using the following steps:

  1. Concatenation of Parameters:
    – All parameters from the payload, including both inner and outer object parameters, must be concatenated into a single string.
    – Parameters must be sorted alphabetically by their names.
    – Each parameter name and value should be combined using an ‘=‘ sign, and each pair should be separated by an ‘&‘ sign.
    – The callbackUrl and hash parameters should be excluded from the hash calculation.
    – The format of the amount parameter value must be as follows: xx.xx. (Example, 100.00)
  2. Exclusion of Empty Parameters:
    – Parameters that have empty or null values must be excluded from the concatenated string.
  3. Appending the Secret Key:
    – A unique secret key, provided to the merchant, must be securely stored and never exposed to unauthorized parties.
    – This secret key must be prepended to the beginning of the generated string.
    – Ensure there is an ‘&‘ sign between the secret key and the concatenated parameters string.
  4. Hashing the Result:
    – The final concatenated string must be hashed using the SHA-256 algorithm.
    – The resulting hash value will then be compared to the hash value received in the payout request for validation.

Example:

{

  "account": "abc123",
  "amount": "100",
  "country": "IN",
  "currency": "INR",
  "email": "email@test.com",
  "ip": "192.0.2.1",
  "midId": "123",
  "orderId": "abc123456",
  "callbackUrl": "https://example.com/callback",
  "data": {
    "accountName": "JohnyCash",
    "bankCity": "",
    "bankCode": "BSBN",
    "city": null,
    "ifsc": "BSBN0001234",
    "mobileNumber": "9123456789"
  }
}

Step 1: Concatenate Parameters according to the rules. After sorting them alphabetically and excluding certain parameters, the resulting string is as follows:

account=abc123&accountName=JohnyCash&amount=100.00&bankCode=BSBN&country=IN&currency=INR&email=email@test.com&ifsc=BSBN0001234&ip=192.0.2.1&midId=123&mobileNumber=9123456789&orderId=abc123456

Step 2: Append the secret key:

mySecretUniqueKey&account=abc123&accountName=JohnyCash&amount=100.00&bankCode=BSBN&country=IN&currency=INR&email=email@test.com&ifsc=BSBN0001234&ip=192.0.2.1&midId=123&mobileNumber=9123456789&orderId=abc123456

Step 3: Hash the resulting string using SHA-256 algorithm:

AC5654FE3128E76AAF2EC79701DA170BFBC77F8AFBB8F9F060E629A62E1B6B0F

Step 4: Send it as a hash parameter value in a payout request.

Payout Statuses

TX TypeEventStatus
Received:TemporaryPENDING
Approved:FinalSUCCESS
Failed:FinalREJECTED, FAIL

Payout Postbacks

Each postback is a general HTTP POST request with a retry mechanism of maximum 5 attempts with a retry possibility every 3 minutes.

We only consume one unique orderId per merchant. After that all transactions with the same ID will be rejected.

Payout Postback Table

TitleFormatExplanation
idStringSystem Transaction ID
orderIdStringMerchant Order ID
statusStringTransaction status
hashStringData signature for encryption

Payout Postback for Rejected payouts

Opt-in to get payout ‘message’ in postbacks.

It is possible to opt-in to get more detailed information about rejected payouts. Contact our tech support for assistance. These settings will be default for new apps after 9th September 2025.

TitleFormatExplanation
messageStringMissing some fields (could be one or many fields)
[Mid 4 rejected due to {Error:{mobile} is missing}]
[Mid 4 rejected due to {Error:{accountname, bankcode, ifsc} is missing}]

Balance
[Mid 4 rejected due to {Insufficient Payout Balance}]
[Mid 4 rejected due to {Min amount is 100.0}]
[Mid 4 rejected due to {Max amount is 100.0}]

Rejected by the bank
[Mid 4 rejected due to {Rejected by the Bank}]

Rejected by multiple MIDs
“[Mid 4 rejected due to {Error:{accountname} is missing}]
[Mid 6 rejected due to {Insufficient Payout Balance}]
[Mid 9 rejected due to {Rejected by the Bank}]”

Payout Postback Sample

header name ‘apikey’, header value <merchant-apikey>

{

  "id": "912z-1zs4-acvb-1bre3",

  "orderId": "merchtx12345",

  "status": "SUCCESS",

  "hash": "<system-generated-hash>",

  "message": "<for-rejected-payouts-only>"

}

Data Signature of Payout

Encryption VariablesValues and explanations
apikey<confidential>
Secret key<confidential>
Encryption formatConcatenated and signed by using SHA-256 algorithm
Parameter orderThe order must be in exact order as per below sample
Parameter examplesecretKey=xxx&id=xx&orderId=xx&status=xx
Result stringWill be signed using SHA-256

Payment Statuses

Previous Page

Status API

Next Page

On this page

Payout Request TableGeneric Payout Request Body & Response SamplePayout Request Optional Data Field Table:Payout API Response FieldsPayout Request Hash GenerationPayout StatusesPayout PostbacksPayout Postback TablePayout Postback for Rejected payoutsPayout Postback SampleData Signature of Payout