Skip to main content

Refund Order

POST/payment-gateway/v1.0/debit/refund.htm

This API is used to refund the order from merchant's platform to DANA. For the easiest integration, use DANA's Libraries to implement Custom Checkout or Hosted Checkout.

API Type
SNAP API
Expected Timeout
8 second
SNAP Service Code
58
Accept
application/json
Content Type
application/json
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)
X-SIGNATURE
string
Required
Signature need to be generated with 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
CHANNEL-ID
string
1 - 5 charactersRequired
Device identification on which the API services is currently being accessed by the end user (customer)
merchantId
string
1 - 64 charactersRequired
Merchant identifier that is unique per each merchant
subMerchantId
string
1 - 32 characters
Sub merchant identifier, known as externalDivisionId must be registered in the DANA system before use. To register a new externalDivisionId, use the Create Division API
Note

In the sandbox, you can find this value in the External Division ID section at https://dashboard.dana.id/sandbox/submerchants

originalReferenceNo
string
1 - 64 characters
Original transaction identifier on DANA system
originalPartnerReferenceNo
string
1 - 64 charactersRequired
Original transaction identifier on partner system
originalExternalId
string
1 - 36 characters
Original external identifier on header message
partnerRefundNo
string
1 - 64 charactersRequired
Reference number from merchant for the refund
refundAmount
money
Required
Refund amount. Contains two sub-fields:
1. Value: 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
externalStoreId
string
1 - 64 characters
Store identifier to indicate to which store this payment belongs to, known as externalShopId must be registered in the DANA system before use. To register a new externalShopId, use the Create Shop API
Note

In the sandbox, you can find this value in the External Shop ID section at https://dashboard.dana.id/sandbox/submerchants

reason
string
1 - 256 characters
Refund reason
additionalInfo
json object
Additional information
additionalInfo.payoutAccountNo
string
1 - 64 characters
Additional information of payout account number. This param need to be filled if want to refund to specific payout account not that specified by DANA
additionalInfo.refundAppliedTime
string
25 characters
Additional information of refund applied time, in format YYYY-MM-DDTHH:mm:ss+07:00. Time must be in GMT+7 (Jakarta time)
additionalInfo.actorType
string
1 - 64 characters
Additional information of actor type, refer to ActorTypeEnum
USER
string
User
MERCHANT
string
Merchant
MERCHANT_OPERATOR
string
Merchant operator
BACK_OFFICE
string
Back office
SYSTEM
string
System
additionalInfo.returnChargeToPayer
string
1 - 64 characters
Additional information of return charge to payer
additionalInfo.destination
string
1 - 64 characters
Additional information of destination
additionalInfo.envInfo
json object
Additional information of environment
sessionId
string
1 - 128 characters
Session identifier
tokenId
string
1 - 128 characters
Token identifier
websiteLanguage
string
1 - 16 characters
Website language
clientIp
string
1 - 32 characters
Client IP address
osType
string
1 - 128 characters
Operating system type
appVersion
string
1 - 128 characters
App version
sdkVersion
string
1 - 128 characters
SDK version
sourcePlatform
string
1 - 32 charactersRequired
Source platform, refer to SourcePlatformEnum
IPG
string
The source platform is independent payment gateway
orderTerminalType
string
1 - 32 charactersRequired
Order terminal type, refer to OrderTerminalTypeEnum
APP
string
Mobile Application
WEB
string
Browser Web
WAP
string
Browser Wap
SYSTEM
string
System Call
terminalType
string
1 - 32 charactersRequired
Terminal type, refer to TerminalTypeEnum
APP
string
Mobile Application
WEB
string
Browser Web
WAP
string
Browser Wap
SYSTEM
string
System Call
orderOsType
string
1 - 128 characters
Order operating system type
merchantAppVersion
string
1 - 128 characters
Merchant App version
extendInfo
string
1 - 4096 characters
Extend information
additionalInfo.auditInfo
json object
Additional information of audit
actionReason
string
1 - 256 characters
Action trigger reason
thirdClientId
string
1 - 32 characters
Third party client identifier
additionalInfo.actorContext
json object
Additional information of actor context
actorId
string
1 - 64 charactersRequired
Actor identifier
actorType
string
1 - 32 charactersRequired
Actor type, refer to ActorTypeEnum
USER
string
User
MERCHANT
string
Merchant
MERCHANT_OPERATOR
string
Merchant operator
BACK_OFFICE
string
Back office
SYSTEM
string
System
additionaInfo.refundOptionBill
array of json object
Additional information of refund option bill
payMethod
string
1 - 64 charactersRequired
Payment method name, refer to PayMethodEnum
BALANCE
string
Payment method with DANA balance
COUPON
string
Payment method with coupon
NET_BANKING
string
Payment method with internet banking
CREDIT_CARD
string
Payment method with credit card
DEBIT_CARD
string
Payment method with debit card
VIRTUAL_ACCOUNT
string
Payment method with virtual account
OTC
string
Payment method with OTC
DIRECT_DEBIT_CREDIT_CARD
string
Payment method with direct debit of credit card
DIRECT_DEBIT_DEBIT_CARD
string
Payment method with direct debit of debit card
ONLINE_CREDIT
string
Payment method with online credit
LOAN_CREDIT
string
Payment method with DANA Cicil
NETWORK_PAY
string
Payment method with e-wallet
Note

Available payment methods in Sandbox include all e-wallets and QRIS (NETWORK_PAY).

transAmount
money
Required
Trans amount. Contains two sub-fields:
1. Value: 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.extendInfo
string
1 - 4096 characters
Additional information of extend
additionalInfo.asyncRefund
string
1 - 5 characters
Additional information of async refund to determine the process of refund whether sync or async. The values is true / false
subMerchantId & externalStoreId

Check yours here: https://dashboard.dana.id/sandbox/submerchants

If you're an aggregator: subMerchantId is mandatory subMerchantId is equal to externalDivisionId, obtained from the Create Division API or DANA Sandbox Dashboard.

If you use QRIS or have outlets/stores under you: externalStoreId is mandatory
externalStoreId can be obtained from the Create Shop API or DANA Sandbox Dashboard.

POST .../payment-gateway/v1.0/debit/refund.htm HTTP/1.2
Content-type: application/json
X-TIMESTAMP: 2020-12-23T07:44:11+07:00
X-SIGNATURE: to fill..
X-PARTNER-ID: 82150823919040624621823174737537
X-EXTERNAL-ID: 41807553358950093184162180797837
CHANNEL-ID: 95221
{
    "merchantId": "00007100010926",
    "originalPartnerReferenceNo": "2020102900000000000001",
    "partnerRefundNo": "239850918204981205970",
    "refundAmount": {
        "value": "10000.00",
        "currency": "IDR"
    }
}
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
originalReferenceNo
string
1 - 64 charactersConditional
Original transaction identifier on DANA system
Conditional Info
Y:= Successfully processed
originalPartnerReferenceNo
string
1 - 64 charactersRequired
Original transaction identifier on partner system
originalExternalId
string
1 - 36 characters
Original external identifier on header message
refundNo
string
1 - 64 charactersConditional
Refund number identifier on DANA system
Conditional Info
Y:= Successfully processed
partnerRefundNo
string
1 - 64 charactersRequired
Reference number from merchant for the refund
refundAmount
[money
Required
Refund amount. Contains two sub-fields:
1. Value: Amount, including the cents
2. Currency: Currency code based on ISO
refundTime
string
25 charactersConditional
Refund time, in format YYYY-MM-DDTHH:mm:ss+07:00. Time must be in GMT+7 (Jakarta time)
Conditional Info
Y:= Successfully processed
additionalInfo
json object
Additional information
Content-type: application/json
X-TIMESTAMP: 2020-12-23T07:44:16+07:00
{
    "responseCode":"2005800",
    "responseMessage":"Successful",
    "originalPartnerReferenceNo":"2020102900000000000001",
    "originalReferenceNo":"2020102977770000000009",
    "originalExternalId":"30443786930722726463280097920912",
    "refundNo":"REF993883",
    "partnerRefundNo":"239850918204981205970",
    "refundAmount":{
        "value":"10000.00",
        "currency":"IDR"
    },
    "refundTime":"2020-12-21T17:21:41+07:00",
    "additionalInfo":{}
}
ResponseCauseSolution
2005800Successful
Success to be processed
Mark Refund Order process as Success
2025800Request In Progress
Transaction is on process
Mark Refund Order process as Pending. Retry request periodically by sending same request payload
4005800Bad Request
General request failed error
Mark Refund Order process as Failed. Retry request with proper parameter
4005801Invalid Field Format
Invalid format for certain field
Mark Refund Order process as Failed. Retry request with proper parameter
4005802Invalid Mandatory Field
Missing or invalid format on mandatory field
Mark Refund Order process as Failed. Retry request with proper parameter
4015800Unauthorized. [reason]
General unauthorized error
Mark Refund Order process as Failed. Retry request with proper parameter
4035802Exceeds Transaction Amount Limit
Exceeds transaction amount limit
Mark Refund Order process as Failed. Try to adjust the amount of money that want to be refunded
4035805Do Not Honor
Account or user status is abnormal
Mark Refund Order process as Failed. Retry request with proper parameter or can contact to DANA to check the user/account status
4035814Insufficient Funds
Insufficient funds of merchant’s account to refund the order
Mark Refund Order process as Failed. Retry request periodically
4035815Transaction Not Permitted.[reason]
Transaction not permitted
Mark Refund Order process as Failed. Retry request periodically or can consult to DANA
4045800Invalid Transaction Status
Invalid transaction status
Mark Refund Order process as Failed. Retry request periodically or can consult to DANA
4045808Invalid Merchant
Merchant does not exist or status abnormal
Mark Refund Order process as Failed. Retry request with proper parameter
4045812Invalid Bill/Virtual Account [Reason]
The bill is blocked/suspended/not found. Virtual account is suspend/not found
Mark Refund Order process as Failed. Retry request with proper parameter
4045813Invalid Amount
The amount doesn't match with what supposed to
Mark Refund Order process as Failed. Retry request with proper parameter
4045818Inconsistent Request
Inconsistent request parameter found for the same partner reference number/transaction identifier
Mark Refund Order process as Pending. Need to investigate the root cause and retry request with proper parameter
4295800Too Many Requests
Maximum transaction limit exceeded
Mark Refund Order process as Pending. Retry request periodically by sending same request payload
5005800General Error
General error non retry-able
Mark Refund Order process as Failed. Retry request periodically
5005801Internal Server Error
Unknown internal server failure, please retry the process again
Mark Refund Order process as Pending. Retry request periodically by sending same request payload
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 by sending same request payload, if still fails mark Refund Order process as Pending
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 Refund Order process as Pending.
  • If empty field/field does not exist, mark Refund Order process as Pending.
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.