Refund Order

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

This API is used to refund the order from merchant's platform to DANA

API Type

SNAP API

Expected Timeout

8 second

SNAP Service Code

58

Accept

application/json

Content Type

applciation/json

This API is used for the following solution:

Gapura Custom Checkout

This solution provides the APIs of the Payment Gateway core system. It is specifically designed for merchants who wants to use their own checkout pages to display payment methods, such as virtual account or QRIS.

---

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

Information of sub merchant identifier

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

originalCaptureNo

string

1 - 64 charactersConditional

DANA's capture identifier. Use to refund the corresponding capture order

Conditional Info

Y:= Auth Payment scenario

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

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 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

VIRTUAL_ACCOUNT

string

Payment method with virtual account

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

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: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5
ORIGIN: www.hostname.com
X-PARTNER-ID: 82150823919040624621823174737537
X-EXTERNAL-ID: 41807553358950093184162180797837
CHANNEL-ID: 95221
{
    "merchantId": "00007100010926",
    "subMerchantId": "310928924949487",
    "originalPartnerReferenceNo": "2020102900000000000001",
    "originalReferenceNo": "2020102977770000000009",
    "originalExternalId": "30443786930722726463280097920912",
    "originalCaptureNo": "202010173821904898012234423",
    "partnerRefundNo": "239850918204981205970",
    "refundAmount": {
        "value": "10000.00",
        "currency": "IDR"
    },
    "externalStoreId": "124928924949487",
    "reason": "Customer complain",
    "additionalInfo": {
        "payoutAccountNo": "20050000000001503276",
        "refundAppliedTime": "2001-07-04T12:08:56+07:00",
        "actorType": "BACK_OFFICE",
        "returnChargeToPayer": true,
        "destination": "TO_BALANCE",
        "envInfo": {
            "sessionId": "8EU6mLl5mUpUBgyRFT4v7DjfQ3fcauthcenter",
            "tokenId": "a8d359d6-ca3d-4048-9295-bbea5f6715a6",
            "websiteLanguage": "en_US",
            "clientIp": "10.15.8.189",
            "osType": "Windows.PC",
            "appVersion": "1.0",
            "sdkVersion": "1.0",
            "sourcePlatform": "IPG",
            "terminalType": "SYSTEM",
            "orderTerminalType": "APP",
            "orderOsType": "IOS",
            "merchantAppVersion": "1.0",
            "extendInfo": "{\"deviceId\":\"CV19A56370e8a00d54293aab8001e4794\", \"bizScenario\":\"SAMPLE_MERCHANT_AGENT\"}"
        },
        "auditInfo": {
            "actionReason": "user claim",
            "thirdClientId": "2016061912345678900987654321234"
        },
        "actorContext": {
            "actorId": "224234234",
            "actorType": "BACK_OFFICE"
        },
        "refundOptionBill": [
        {
            "payMethod": "BALANCE",
            "transAmount": {
            "currency": "IDR",
            "value": "100.00"
            }
        }
        ],
        "extendInfo": {},
        "asyncRefund": "true"
    }
}

---

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

originalCaptureNo

string

1 - 64 charactersConditional

DANA’s capture identifier. Use to refund the corresponding capture order

Conditional Info

Y:= Auth Payment scenario

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",
    "originalCaptureNo": "202010173821904898012234423",
    "refundNo":"REF993883",
    "partnerRefundNo":"239850918204981205970",
    "refundAmount":{
        "value":"10000.00",
        "currency":"IDR"
    },
    "refundTime":"2020-12-21T17:21:41+07:00",
    "additionalInfo":{}
}

---

Response	Cause	Solution
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.