Refund

Requirements

Before start integration, you must have retrieved credentials from Acquirer.

If you don't have the credentials yet, we can help to facilitate you to get one. Here is the flow to get credentials:

Direct API - Direct Debit CIMB SNAP Payment

Direct Debit Refund

Type	Value	Description
HTTP Method	POST
API endpoint (Sandbox)	https://api-sandbox.doku.com/direct-debit/[acquirer-name]/v1.0/debit/refund	Possible Values for [acquirer-name] : ovo, cimb, allobank, bri
API endpoint (Production)	https://api.doku.com/direct-debit/[acquirer-name]/v1.0/debit/refund	Possible Values for [acquirer-name] : ovo, cimb, allobank, bri

Here is the sample of request header to perform Refund :

X-PARTNER-ID: MCH-0001-10791114622547
X-EXTERNAL-ID: 1684987418452706687
X-TIMESTAMP: 2023-01-27T15:58:59+07:00
X-IP-ADDRESS: 192.168.23.23
X-DEVICE-ID: 912f12e223624d2e94828b1681992be3
X-SIGNATURE: hMac123234nsjkdfhajnkssfhgjklsfsdfdfgdfgdfg124dfgfgh

Request Header Explanation

Parameter	Description
X-PARTNER-ID	Unique ID for a partner (DOKU'S Client ID)
X-EXTERNAL-ID	Numeric String. Reference number that should be unique in the same day (request-id)
X-TIMESTAMP	Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format
X-IP-ADDRESS	IP address of the end user (customer) using IPv4 format. Notes: Mandatory for Allobank (Min:10, Max:15), Optional for rest of acquirer
X-SIGNATURE	algoritma symmetric signature HMAC_SHA512 (clientSecret, stringToSign) dengan formula stringToSign = HTTPMethod +”:“+ EndpointUrl +":"+ AccessToken +":“+ Lowercase(HexEncode(SHA-256(minify(RequestBody))))+ ":“ + TimeStamp

Here is the sample of request body for Refund Process :

{
  "originalPartnerReferenceNo": "REFUND-TESTING-STG-P2M-1224",
  "originalExternalId": "10052019",
  "partnerRefundNo": "239850918204981205970",
  "refundAmount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "reason": "Customer complain",
  "additionalInfo": {
    "bankCardToken": "123412341234"
   }
}

Refund API Explanation

Parameter	Type	Mandatory	Description
originalPartnerReferenceNo	string (64)	Mandatory	Transaction identifier on service consumer system, will be used as invoice number. For CIMB, Max length : 12
originalExternalId	string	Optional	Original customer reference number
partnerRefundNo	string (64)	Mandatory	Unique refund identifier on service consumer system
refundAmount	object	Mandatory
refundAmount.value	object	Mandatory	Total amount ends in decimal .00 if currency is IDR
refundAmount.currency	string (3)	Mandatory	IDR
reason	string (256)	Optional
additionalInfo	object	Optional
additionalInfo.bankCardToken	string	Mandatory	Customer's token that are used to process original transaction

API Response

After hitting the above API request, DOKU will give the response.

Type	Value
HTTP Status	201
Result	CREATED

Here is the sample response header:

X-PARTNER-ID: MCH-0001-10791114622547
X-EXTERNAL-ID: 1684987418452706687
X-TIMESTAMP: 2023-01-27T15:58:59+07:00
X-IP-ADDRESS: 192.168.23.23
X-DEVICE-ID: 912f12e223624d2e94828b1681992be3
X-SIGNATURE: hMac123234nsjkdfhajnkssfhgjklsfsdfdfgdfgdfg124dfgfgh

Response Header Explanation

Parameter	Description
X-PARTNER-ID	Unique ID for a partner (DOKU'S Client ID)
X-EXTERNAL-ID	Numeric String. Reference number that should be unique in the same day (request-id)
X-TIMESTAMP	Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format
X-IP-ADDRESS	IP address of the end user (customer) using IPv4 format. Notes: Mandatory for Allobank (Min:10, Max:15), Optional for rest of acquirer
X-SIGNATURE	algoritma symmetric signature HMAC_SHA512 (clientSecret, stringToSign) dengan formula stringToSign = HTTPMethod +”:“+ EndpointUrl +":"+ AccessToken +":“+ Lowercase(HexEncode(SHA-256(minify(RequestBody))))+ ":“ + TimeStamp

Here is the sample of response body:

1. OVO

{
    "responseCode": "2005800",
    "responseMessage": "Request has been processed successfully",
    "originalPartnerReferenceNo": "REFUND-TESTING-STG-P2M-1224",
    "originalReferenceNo": "TESTING-STG-P2M-1224",
    "refundNo": "REF993883",
    "partnerRefundNo": "239850918204981205970",
    "refundAmount": {
        "value": "10000.00",
        "currency": "IDR"
    },
    "refundTime": "2020-12-21T17:21:41+07:00"
}

OVO Refund Explanation

Parameter	Type	Mandatory	Description
responseCode	string (7)	Mandatory	Response code as defined in SNAP Regulation
responseMessage	string (128)	Mandatory	Response message as defined in SNAP Regulation
originalPartnerReferenceNo	string (64)	Optional	Original Transaction identifier on service consumer system
originalReferenceNo	string (2048)	Optional	Original Transaction identifier on service consumer system
refundNo	string (64)	Optional
refundAmount	object	Optional
refundAmount.value	numeric (16,2)	Mandatory	URL to redirect user to Acquirer's webview to let customer finish OTP
refundAmount.currency	string (3)	Mandatory	IDR
refundTime	string (25)	Mandatory	Refund Time, ISO 8601

2. Allo Bank

{
    "responseCode": "2005800",
    "responseMessage": "Request has been processed successfully",
    "originalPartnerReferenceNo": "REFUND-TESTING-STG-P2M-1224",
    "originalReferenceNo": "TESTING-STG-P2M-1224",
    "refundNo": "REF993883",
    "partnerRefundNo": "239850918204981205970",
    "refundAmount": {
        "value": "10000.00",
        "currency": "IDR"
    },
    "refundTime": "2020-12-21T17:21:41+07:00"
}

Allo Bank Refund Explanation

Parameter	Type	Mandatory	Description
responseCode	string (7)	Mandatory	Response code as defined in SNAP Regulation
responseMessage	string (128)	Mandatory	Response message as defined in SNAP Regulation
originalPartnerReferenceNo	string (64)	Optional	Original Transaction identifier on service consumer system
originalReferenceNo	string (2048)	Optional	Original Transaction identifier on service consumer system
refundNo	string (64)	Optional
refundAmount	object	Optional
refundAmount.value	numeric (16,2)	Mandatory	URL to redirect user to Acquirer's webview to let customer finish OTP
refundAmount.currency	string (3)	Mandatory	IDR
refundTime	string (25)	Mandatory	Refund Time, ISO 8601