Skip to main content

Customer Top Up

POST/v1.0/emoney/topup.htm

This API is used to trigger top up request from merchant to DANA.

API Type
SNAP API
Expected Timeout
8 second
SNAP Service Code
38
Accept
application/json
Content Type
application/json

Idempotent Key & Usage Rules​

  • Idempotent is controlled by Idempotent Key (partnerReferenceNo). With two scenarios which are:

    • Idempotent success: Request has been created and the process was successful, will return 2003800.
    • Idempotent failed: Request has been created and the process was failed, will return 5003800.

  • Before merchant wants to retry the request with the same partnerReferenceNo, merchant should ensure the consistency of request such as amount or payee user based on access token/customerNumber.

Retry Mechanism​

The following are the details of the retry mechanism in case merchant needs to initiate a retry process:

  • Retry is a mandatory process.
  • The maximum retry is 5 times.
  • Using the following interval time: 5, 10, 20, 40, 60, till merchant’s cut off (in seconds).
Content-type
string
1 - 127 charactersRequired
Content type, value always application/json
Authorization
string
1 - 2048 charactersConditional
Contains bearer JWT token, which has been obtained from Authorization Token Request API
Conditional Info
Y:= Signature option is symmetric approach
Authorization-Customer
string
1 - 512 charactersConditional
  • Contains customer token, which has been obtained from binding process
  • If request is coming from user interaction, this field is mandatory. If not, just filled customerNumber
Conditional Info
Y:= customerNumber is not exist
X-TIMESTAMP
string
25 charactersRequired
Transaction date time, in format YYYY-MM-DDTHH:mm:ss+07:00. Time must be in GMT+7 (Jakarta time)
X-SIGNATURE
string
Required
Signature need to be generated with symmetricSignature or asymmetricSignature method
ORIGIN
string
Origin domain
X-PARTNER-ID
string
1 - 36 charactersRequired
Unique identifier for partner was generated by DANA, or known as clientId
X-EXTERNAL-ID
string
1 - 36 charactersRequired
Unique messaging reference identifier generated by merchant and should be unique within the same day
X-IP-ADDRESS
string
15 characters
IP address of the end user (customer) using IPv4 format
X-DEVICE-ID
string
1 - 400 charactersConditional
Device identification on which the API services is currently being accessed by the end user (customer). Sample:
  • Web Application:
    • Mozilla / 5.0 (Windows NT 10.0; Win64; x64)
    • AppleWebKit / 537.36 (KHTML, like Gecko)
    • Chrome / 75.0.3770.100
    • Safari / 537.36 OPR / 62.0.3331.99
  • Mobile Application:
    • Android:android-20013adf6cdd8123f
    • iOS: 72635bdfd223yvjm7246n sdj34hd4559393kjh42"
Conditional Info
Y:= Using Authorization-Customer
CHANNEL-ID
string
1 - 5 charactersRequired
Device identification on which the API services is currently being accessed by the end user (customer)
partnerReferenceNo
string
1 - 64 charactersRequired
Unique transaction identifier in partner system for each transaction.
Note: When retrying after a timeout or unexpected response, use the same partnerReferenceNo as in the original request
customerNumber
string
1 - 32 charactersConditional
Customer account number, in format 628xxx
Conditional Info
Y:= Authorization-Customer is not exist
amount
money
Required
Amount. Contains two sub-fields:
1. Value: Transaction amount, including the cents
2. Currency: Currency code based on ISO
value
string
1 - 19 charactersRequired
Value of amount. Following ISO-4217, for IDR the value includes 2 decimal digits separated with point e.g.,IDR 10.000,- will be placed with 10000.00
currency
string
1 - 3 charactersRequired
Currency
feeAmount
money
Required
Fee amount. Contains two sub-fields:
1. Value: Transaction amount, including the cents
2. Currency: Currency code based on ISO
value
string
1 - 19 charactersRequired
Value of amount. Following ISO-4217, for IDR the value includes 2 decimal digits separated with point e.g.,IDR 10.000,- will be placed with 10000.00
currency
string
1 - 3 charactersRequired
Currency
transactionDate
string
25 characters
Transaction date, in format YYYY-MM-DDTHH:mm:ss+07:00. Time must be in GMT+7 (Jakarta time)
sessionId
string
1 - 25 characters
Session identifier
categoryId
numeric
1 - 10 characters
Category identifier
notes
string
1 - 255 characters
Transaction notes
additionalInfo
json object
Additional information
additionalInfo.extendInfo
string
1 - 4096 characters
Additional information of extend
additionalInfo.accountType
string
1 - 64 characters
Additional information of account type
additionalInfo.fundType
string
1 - 64 charactersRequired
Additional information of top up fund type, value always AGENT_TOPUP_FOR_USER_CLEARING
additionalInfo.accessToken
string
1 - 512 charactersConditional
  • Contains customer token, which has been obtained from binding process
  • If request is coming from user interaction, this field is mandatory. If not, just filled customerNumber
Conditional Info
Y:= customerNumber is not exist
POST .../v1.0/emoney/topup.htm HTTP/1.2
Content-type: application/json
Authorization: Bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a
Authorization-Customer: Bearer fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a
X-TIMESTAMP: 2020-12-21T17:07:11+07:00
X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5
ORIGIN: www.hostname.com
X-PARTNER-ID: 82150823919040624621823174737537
X-EXTERNAL-ID: 41807553358950093184162180797837
X-IP-ADDRESS: 172.24.281.24
X-DEVICE-ID: 09864ADCASA
CHANNEL-ID: 95221
{
  "partnerReferenceNo": "2020102900000000000001",
  "customerNumber": "6281773628883",
  "amount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "feeAmount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "transactionDate": "2020-12-21T14:56:11+07:00",
  "sessionId": "883737GHY8839",
  "categoryId": "6",
  "notes": "notes test",
  "additionalInfo": {
    "extendInfo": "{\"memo\": \"topup order memo\"}",
    "accountType": "NAME_DEPOSIT",
    "fundType": "AGENT_TOPUP_FOR_USER_CLEARING",
    "accessToken" : "fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a"
  }
}
Content-type
string
1 - 127 charactersRequired
Content type, value always application/json
X-TIMESTAMP
string
25 charactersRequired
Transaction date time, in format YYYY-MM-DDTHH:mm:ss+07:00. Time must be in GMT+7 (Jakarta time)
responseCode
string
7 charactersRequired
Refer to response code list
responseMessage
string
1 - 150 charactersRequired
Refer to response code list
referenceNo
string
1 - 64 charactersConditional
Transaction identifier on DANA system
Conditional Info
Y:=Success
partnerReferenceNo
string
1 - 64 charactersRequired
Unique transaction identifier in partner system for each transaction.
Note: When retrying after a timeout or unexpected response, use the same partnerReferenceNo as in the original request
sessionId
string
1 - 25 characters
Session identifier
customerNumber
string
1 - 32 characters
Customer account number, in format 628xxx
amount
money
Required
Amount. Contains two sub-fields:
1. Value: Transaction amount, including the cents
2. Currency: Currency code based on ISO
value
string
1 - 19 charactersRequired
Value of amount. Following ISO-4217, for IDR the value includes 2 decimal digits separated with point e.g.,IDR 10.000,- will be placed with 10000.00
currency
string
1 - 3 charactersRequired
Currency
additionalInfo
json object
Additional information
Content-type: application/json
X-TIMESTAMP: 2020-12-21T14:36:19+07:00
{
  "responseCode": "2003800",
  "responseMessage": "Successful",
  "referenceNo": "2020102977770000000009",
  "partnerReferenceNo": "2020102900000000000001",
  "sessionId": "883737GHY8839",
  "customerNumber": "628187366363",
  "amount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "additionalInfo": {
  }
}
ResponseCauseSolution
2003800Successful
Success to be processed
Mark Customer Top Up process as Success
4003800Bad Request
General request failed error
Mark Customer Top Up process as Failed. Retry request with proper parameter
4003801Invalid Field Format
Invalid format for certain field
Mark Customer Top Up process as Failed. Retry request with proper parameter
4003802Invalid Mandatory Field
Missing or invalid format on mandatory field
Mark Customer Top Up process as Failed. Retry request with proper parameter
4013800Unauthorized. [reason]
General unauthorized error
Mark Customer Top Up process as Failed. Retry request with proper parameter
4013801Invalid Token (B2B)
Authorization token are invalid, perhaps due to token expiry for B2B
Mark Customer Top Up process as Failed. Retry request with proper parameter
4013802Invalid Customer Token
Customer token are invalid, perhaps due to token expiry
Mark Customer Top Up process as Failed. Retry request with proper parameter
4013804Customer Token Not Found
Customer token not found in the system. This occurs on any API that requires token as input parameter
Mark Customer Top Up process as Failed. Retry request with proper parameter
4033802Exceeds Transaction Amount Limit
Exceeds transaction amount limit
Mark Customer Top Up process as Failed. Retry request with proper amount
4033803Suspected Fraud
Suspected fraud
Mark Customer Top Up process as Failed. Contact DANA to check the user/account status
4033805Do Not Honor
Account or user status is abnormal
Mark Customer Top Up process as Failed. Contact DANA to check the user/account status
4043818Inconsistent Request
Inconsistent request parameter found for the same partner reference number/transaction identifier
Mark Customer Top Up process as Success. Contact DANA to check status of Customer Top Up process
4293800Too Many Requests
Maximum transaction limit exceeded
Mark Customer Top Up process as Pending. Hold the money and retry request periodically
5003800General Error
General error non retry-able
Mark Customer Top Up process as Failed. Retry new Customer Top Up process
5003801Internal Server Error
Unknown internal server failure, please retry the process again
Mark Customer Top Up process as Pending. Hold the money and retry request periodically
Total Timeout
Total timeout, the client side does not get any responses from the server side (can be due to network issue, server slowing down, and so on)
Do a retry maximum 3 attempts, if still fails mark Customer Top Up process as Pending and hold the money
Unexpected response (empty field/field does not exist/undefined response code)
The server does not produce expected responses (can be due to hardware failure, bugs, and so on)
  • If the response code prefix are 202 and 5XX, mark Customer Top Up process as Pending and hold the money
  • If empty field/field does not exist, mark Customer Top Up process as Pending and hold the money
ask AIAI Assistant
Need help with our documentation?
Start from our frequently asked questions or feel free to ask anything else.

AI generated responses may contain mistakes.