Customer Top Up

POST/v1.0/emoney/topup.htm

This API is used for merchant to do top up request to DANA

API Type

SNAP API

Expected Timeout

8 second

SNAP Service Code

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, refer to Apply Token API
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: 72635bdfd223yvjm7246nsdj34hd4559393kjh42"

Conditional Info

Y:= Authorization Customer is exist

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:

Value: Amount, including the cents
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:

Value: Amount, including the cents
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, i.e.; AGENT_TOPUP_FOR_USER_SETTLE

additionalInfo.externalDivisionId

string

1 - 64 characters

Additional information of external division identifier. This parameter only used for Top Up Disbursement subMerchant (fundType: AGENT_TOPUP_FOR_USER_SETTLE).
Notes:
The required of this parameter is Optional, but if additionalInfo.chargeTarget has value DIVISION then the required of this parameter will be changed to Mandatory

additionalInfo.chargeTarget

string

1 - 64 characters

Additional information of charge target. This parameter only used for Top Up Disbursement subMerchant. The value are:

null
DIVISION
MERCHANT

if the value is DIVISION, externalDivisionId will be Mandatory

additionalInfo.accessToken

string

1 - 512 charactersConditional

Contains customer token, which has been obtained from binding process, refer to Apply Token API
If request is coming from user interaction, this field is mandatory.
If not, just filled customerNumber

Conditional Info

Y:= customerNumber is not exist

additionalInfo.customerId

string

1 - 32 characters

Public user identifier of DANA user.
Note: If used, requires customerNumber to be filled with default phone number literal "620000000000"

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_SETTLE",
    "externalDivisionId": "91080916Division",
    "chargeTarget": "DIVISION",
    "accessToken": "fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a",
    "customerId": "20200519111215830121DANAW3ID009200305573"
  }
}

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:

Value: Transaction amount, including the cents
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": {}
}

Response	Cause	Solution
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
4033814Insufficient Funds	Insufficient funds	Mark Customer Top Up process as Failed. Contact DANA to top up deposit balance
4033815Transaction Not Permitted.[reason]	Transaction not permitted	Mark Customer Top Up process as Failed. Contact DANA to check merchant configuration
4033818Inactive Card/Account/Customer	Indicates inactive account	Mark Customer Top Up process as Failed. Contact DANA to check merchant configuration
4033820Merchant Limit Exceed	Merchant aggregated purchase amount on that day exceeds the agreed limit	Mark Customer Top Up process as Failed. Contact DANA to check merchant configuration
4043808Invalid Merchant	Merchant does not exist or status abnormal	Mark Customer Top Up process as Failed. Contact DANA to check merchant configuration
4043811Invalid Card/Account/Customer [info]/Virtual Account	Card information may be invalid, or the card account may be blacklisted, or Virtual Account number maybe invalid	Mark Customer Top Up process as Failed. Contact DANA to check merchant configuration
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
5043800Timeout	Timeout from the issuer	Mark Customer Top Up process as Pending & retry request periodically or Mark Customer Top Up as Success & hold the money
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)	Mark Customer Top Up process as Pending & retry request periodically or Mark Customer Top Up as Success & 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 & retry request periodically or Mark Customer Top Up as Success & hold the money If empty field/field does not exist, mark Customer Top Up process as Pending & retry request periodically or Mark Customer Top Up as Success & hold the money

Idempotent Key & Usage Rules​

Retry Mechanism​

Idempotent Key & Usage Rules

Retry Mechanism