--- title: Refund Transaction - API QRIS SNAP slug: nicepay-api-snap-refund-transaction-qris description: Informasi tentang Refund Transaction - API QRIS SNAP yang terdapat pada sistem NICEPAY image: https://archbee-image-uploads.s3.amazonaws.com/ZHvSjR5ZrsoxwKbJa3xmo/37kaQ0-rkRMk476_PqrCR_microsoftteams-image.png icon: {"faIcon":"fa-solid fa-book"} docTags: createdAt: 2023-02-17T10:07:14.000Z --- # Tentang Refund Transaction - API QRIS SNAP *** API dengan standar SNAP ini digunakan untuk melakukan proses pengembalian dana transaksi pada metode pembayaran QRIS. ## Aturan dan Kondisi Pengembalian Dana Transaksi *** Bagian ini akan menjelaskan terkait aturan dan kondisi pengembalian dana yang berlaku pada saat pembatalan transaksi. | **Kondisi Pengembalian Dana ShopeePay** | **Ketentuan Pengembalian Dana** | | -------------------------------------------------------- | ---------------------------------------------------------- | | Pembatalan sebelum transaksi diproses bayar. | Status transaksi berubah menjadi Kedaluwarsa (status `5`). | | Pengembalian dana secara daring untuk transaksi umum. | Hanya berlaku jika transaksi *belum mencapai 365 hari*. | | Pengembalian dana diajukan pada pukul 00:00 - 05:00 WIB. | Otomatis **Rejected**. | | Transaksi *Off-Us* ≤ 7 hari. | **Online Refund** tersedia. | | Transaksi *Off-Us* 8-365 hari. | Dialihkan ke **Manual Refund**. | | Transaksi *Off-Us* > 365 hari. | Pengembalian dana tidak lagi tersedia. | :::hint{type="info"} Silakan kunjungi halaman [Integrasi & Testing QRIS](docId\:tCFbU7--Xd0Sm5_rQ00_w) untuk informasi lebih lengkap terkait aturan dan kondisi pengembalian dana transaksi. ::: # Refund Transaction - API QRIS SNAP *** :::hint{type="warning"} Silakan mengajukan akses token terlebih dahulu sebelum menggunakan Refund Transaction API melalui bagian [Request Access Token API - SNAP](docId\:GcGqBIYXG1Etcd0Ji9cHX). ::: | **Service Code** | `78` | | ---------------- | ------------------------------------ | | **API Endpoint** | `/nicepay/api/v1.0/qr/qr-mpm-refund` | | **HTTP Method** | **POST** | | **Description** | Refund Transaction QRIS API | | **Content-type** | `application/json` | ## Request Header Parameter for Refund Transaction - API QRIS SNAP *** | **Nama Parameter Header** | **Tipe** | **Kebutuhan** | **Deskripsi** | **Contoh** | | ------------------------- | ----------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | `Content-Type` | String (127) | Mandatory | Type of the content | `Application/Json` | | `X-TIMESTAMP` | String
(25) | Mandatory | Using ISO 8601 as timestamp format.
Transaction date time, in format `YYYYMMDDTHH:mm:ss+07:00`.
Time must be in GMT+7 (Jakarta time).
`2022-03-21T10:11:40+07:00`. | | | `Authorization` | String (Variable) | Mandatory | "Bearer" + \{`access_token`} | | | `X-SIGNATURE` | String (Variable) | Mandatory | Signature will be generated by Merchant.
[Panduan X-Signature - Symmetric](docId\:UZex33ReLyENKOgbJJnYp) | | | `X-PARTNER-ID` | String
(20) | Mandatory | NICEPAY Client ID (`MID`) | IONPAYTEST | | `X-EXTERNAL-ID` | String
(40) | Mandatory | Unique messaging Reference ID generated by Merchant. Numeric String. Reference number that should be unique in every transaction in One Day. | | | `CHANNEL-ID` | String
(20) | Mandatory | Unique Channel Merchant Credential ID Number.
Client ID + "01" = Channel ID
`"IONPAYTEST" + "01" = "IONPAYTEST01"` | IONPAYTETS01 | ## Request Body Parameter for Refund Transaction - API QRIS SNAP *** | **Nama Parameter BI** | **Tipe Parameter** | **Kebutuhan** | **Parameter NICEPAY** | **Deskripsi** | **Contoh** | | ---------------------------- | ------------------ | ------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | `originalReferenceNo` | String (40) | Mandatory | `tXId` | NICEPAY Transaction ID or Identifier | IONPAYTEST08202106091121206416 | | `originalPartnerReferenceNo` | String (40) | Mandatory | `referenceNo` | Unique Transaction ID from Merchant | ncpy20221017161458 | | `partnerRefundNo` | String (40) | Mandatory | `merReferenceRefundNo` | Merchant Refund Reference Number | ncpy20221017161458 | | `merchantId` | String (10) | Mandatory | `iMid` | NICEPAY Merchant ID | IONPAYTEST | | `externalStoreId` | String (32) | Mandatory | `storeCd` | Merchant ID from Acquirer Pay Side | NICEPAY | | `refundAmount` | Object | Mandatory | | `"refundAmount": { `
` "value": ..., `
` "currency": ... `
` },` | | | - `value` | String (12) | Mandatory | `amt` | Transaction Amount

Note: Amount Format, currently only supported IDR (Indonesian Currency Rupiah) then value includes 2 decimal digits which are seperated by a dot (.) | 10000.00 | | `currency` | String (3) | Mandatory | `currency` | Default Value: IDR | IDR | | `reason` | String (256) | Mandatory | `cancelMsg` | Reason of Cancel | Refund Trans | | `additionalInfo` | Object | Mandatory | - | `"additionalInfo": { `
` "cancelType" : "1" `
` }` | - | | `cancelType` | String (2) | Mandatory | `cancelType` | `1`: Full Cancellation
`2`: Partial Cancellation | 1 | ## Response Parameter for Refund Transaction - API QRIS SNAP *** | **Nama Parameter BI** | **Tipe Parameter** | **Kebutuhan** | **Parameter NICEPAY** | **Deskripsi** | **Contoh** | | --------------------- | ------------------ | ------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | `responseCode` | String (7) | Mandatory | `responseCd` | Error code to specify the error returned
[General Response Code and Message - API SNAP](docId\:lKqJXSl5CMKdXYXxHYYSs) | 2007800 | | `responseMessage` | String (150) | Mandatory | `responseMsg` | Debug message to provide more information | Successful | | `originalReferenceNo` | String (40) | Mandatory | `canceltXid` | NICEPAY Transaction ID or Identifier that need to be cancelled | IONPAYTEST082021017161458 | | `refundNo` | String (40) | Mandatory | `tXid` | Unique Refund ID from NICEPAY | IONPAYTEST08202106091121206416 | | `partnerRefundNo` | String (40) | Mandatory | `merReferenceRefundNo` | Merchant refund reference number | ncpy20221017161458 | | `refundAmount` | Object | Mandatory | | `"refundAmount": { `
` "value": "10000.00", `
` "currency": "IDR" `
` }` | | | - `value` | String (12) | Mandatory | `amt` | Transaction Amount

Note: Amount Format, currently only supported IDR (Indonesian Currency Rupiah) then value includes 2 decimal digits which are seperated by a dot (.) | 10000.00 | | - `currency` | String (3) | Mandatory | `currency` | Default Value: IDR | IDR | | `refundTime` | String (25) | Mandatory | `transDt`,
`transTm` | Update time of the individual Refund.
The value will be returned for successful invalidate request.
Using ISO-8601 Timestamp Format.
(`YYYY-MM-DDTHH:MM:SS`) | 2022-07-20T07:15:00+07:00 | | `additionalInfo` | Object | Mandatory | - | `"additionalInfo": { `
` "cancelTrxSn": "07202210051341224326" `
`}` | - | | - `cancelTrxSn` | String (32) | Mandatory | - | Refund Transaction Number From Acquirer Side | 07202210051341224326 | ## Sample Parameter for Refund Transaction - API QRIS SNAP *** ### Request Parameter :::CodeblockTabs cURL ```curl curl -X POST \ 'https://dev.nicepay.co.id/nicepay/api/v1.0/qr/qr-mpm-refund' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJJT05QQVlURVNUIiwiaXNzIjoiTklDRVBBWSIsIm5hbWUiOiJCUklOIiwiZXhwIjoiMjAyNC0wMi0xMVQwODowOTozNVoifQ==.aIybLX36dYwfFvW7dcoenXkOe2EAwIYq84ZtPuIf3K8=' \ -H 'X-TIMESTAMP: 2024-12-31T10:11:40+07:00' \ -H 'X-SIGNATURE: ufBw7R8RhW79IOiV/Hlv607M60qzAYBv8uZmbSrYb6/Thlo/FhQVP4xRyelUehoSS9o+QS6vWTKb/ygtucC+tQ==' \ -H 'X-PARTNER-ID: IONPAYTEST' \ -H 'X-EXTERNAL-ID: eXid202402111402271707638098' \ -H 'CHANNEL-ID: IONPAYTEST' \ -d '{"originalReferenceNo":"ncpy20221017161458","originalPartnerReferenceNo":"IONPAYTEST08202106091121206416","partnerRefundNo":"ncpy20221017161458","merchantId":"IONPAYTEST","externalStoreId":"NICEPAY","refundAmount":{"value":"10000.00","currency":"IDR"},"reason":"Refund Trans","additionalInfo":{"cancelType":"1"}}' ``` Node.js ```nodejs // Data from the QRIS Refund request const partnerId = "IONPAYTEST"; const channelId= "IONPAYTEST"; const externalId = "eXid202402111402271707638098"; const timestamp = "2024-12-31T10:11:40+07:00"; const accessToken = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJJT05QQVlURVNUIiwiaXNzIjoiTklDRVBBWSIsIm5hbWUiOiJCUklOIiwiZXhwIjoiMjAyNC0wMi0xMVQwODowOTozNVoifQ==.aIybLX36dYwfFvW7dcoenXkOe2EAwIYq84ZtPuIf3K8="; // Step 1: Configure the config const config = { isProduction: false, privateKey: "MERCHANT_PRIVATE_KEY", clientSecret: "MERCHANT_CLIENT_SECRET", clientId: partnerId, isCloudServer: false, }; // Step 2: Define the QRIS Refund Request Parameters let parameterRefund = { body: { originalReferenceNo: "ncpy20221017161458", originalPartnerReferenceNo: "IONPAYTEST08202106091121206416", partnerRefundNo: "ncpy20221017161458", merchantId: partnerId, externalStoreId: "NICEPAY", refundAmount: { value: "10000.00", currency: "IDR", }, reason: "Refund Trans", additionalInfo: { cancelType: "1", }, }, headers: { X_TIMESTAMP: timestamp, X_PARTNER_ID: partnerId, X_EXTERNAL_ID: externalId, CHANNEL_ID: channelId, }, }; // Step 3: Execute the Refund Request let endPoint = `/api/v1.0/qr/qr-mpm-refund`; let snap = new Snap(config); let response = snap .requestSnapTransaction(parameterRefund, endPoint, accessToken, "POST"); ``` ```java String accessToken = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJJT05QQVlURVNUIiwiaXNzIjoiTklDRVBBWSIsIm5hbWUiOiJCUklOIiwiZXhwIjoiMjAyNC0wMi0xMVQwODowOTozNVoifQ==.aIybLX36dYwfFvW7dcoenXkOe2EAwIYq84ZtPuIf3K8="; // Step 1: Initialize the NICEPay Configuration NICEPay config = NICEPay.builder() .isProduction(false) .clientSecret("YOUR_CLIENT_SECRET") // Placeholder for actual secret .partnerId("IONPAYTEST") .externalID("eXid202402111402271707638098") .timestamp("2024-12-31T10:11:40+07:00") .privateKey("YOUR_PRIVATE_KEY") // Placeholder for actual key .build(); // Step 2: Define the QRIS Refund Request Body Cancel requestData = Cancel.builder() .merchantId("IONPAYTEST") .externalStoreId("NICEPAY") .originalReferenceNo("ncpy20221017161458") .originalPartnerReferenceNo("IONPAYTEST08202106091121206416") .partnerRefundNo("ncpy20221017161458") .reason("Refund Trans") .refundAmount("10000.00", "IDR") .additionalInfo(Map.of("cancelType", "1")) .build(); // Step 3: Execute the QRIS Refund NICEPayResponse result = SnapCancelService.callServiceQrisRefund(requestData, accessToken, config); ``` ```python CLIENT_ID = "IONPAYTEST" EXTERNAL_STORE_ID = "NICEPAY" ORIGINAL_REF_NO = "ncpy20221017161458" ORIGINAL_PARTNER_REF_NO = "IONPAYTEST08202106091121206416" PARTNER_REFUND_NO = "ncpy20221017161458" REFUND_REASON = "Refund Trans" REFUND_VALUE = "10000.00" bodyCreateToken = ( builderAccessToken.BuildAccessToken() .setGrantType("client_credentials") .setAdditionalInfo("") .build() ) refundAmount = { "value": REFUND_VALUE, "currency": "IDR" } additionalInfo = { "cancelType": "1" } bodyQrisInquiry = ( builderQris.BuildQrisRefund() .setMerchantId(CLIENT_ID) .setExternalStoreId(EXTERNAL_STORE_ID) .setOriginalReferenceNo(ORIGINAL_REF_NO) .setOriginalPartnerReferenceNo(ORIGINAL_PARTNER_REF_NO) .setPartnerRefundNo(PARTNER_REFUND_NO) .setRefundAmount(refundAmount) .setReason(REFUND_REASON) .setAdditionalInfo(additionalInfo) .build() ) environment = (builderEnvironment.BuildEnvironment() .isCloud(False) .isProduction(False) .build()) result = SnapService.serviceTransaction(bodyCreateToken.jsonAccessToken(), bodyQrisInquiry.jsonQrisRefund(), ConstantsEndpoints.refundQris(), environment) ``` C# ```csharp const string NEW_CLIENT_ID = "IONPAYTEST"; const string NEW_EXTERNAL_ID = "eXid202402111402271707638098"; const string NEW_CHANNEL_ID = "IONPAYTEST"; const string REFUND_AMOUNT = "10000.00"; const string REFUND_CURRENCY = "IDR"; const string ORIGINAL_REF_NO = "ncpy20221017161458"; const string ORIGINAL_PARTNER_REF_NO = "IONPAYTEST08202106091121206416"; const string EXTERNAL_STORE_ID = "NICEPAY"; const string CANCEL_TYPE = "1"; const string REASON = "Refund Trans"; TestingConstant config = new TestingConstant(); string privateKey = ; string timestamp = DateTimeOffset.Now.ToString("yyyy-MM-ddTHH:mm:sszzz"); string clientSecret = config.ClientSecret; string channelId = NEW_CHANNEL_ID; string random = SignatureGeneratorUtils.GenerateRandomNumberString(8); bool isProduction = false; bool isCloudServer = true; string signature = SignatureGeneratorUtils.GenerateSignature(privateKey, NEW_CLIENT_ID, timestamp); var tokenRequester = new AccessTokenRequester(); string accessTokenResponse = await tokenRequester.GetAccessTokenAsync(NEW_CLIENT_ID, signature, timestamp, isProduction, isCloudServer); dynamic accessTokenObject = JObject.Parse(accessTokenResponse); string accessToken = accessTokenObject.accessToken; Console.WriteLine("Inquiry Ewallet Akses token: " + accessToken); ApiEndpoints apiEndpoints = new ApiEndpoints(); APIService qrisService = new APIService(apiEndpoints, clientSecret, NEW_CLIENT_ID, channelId, isProduction, isCloudServer); SnapQrisServices snapQrisServices = new SnapQrisServices(NEW_CLIENT_ID); string createRequestBody = snapQrisServices.GenerateRefundQris( originalReferenceNo: ORIGINAL_REF_NO, originalPartnerReferenceNo: ORIGINAL_PARTNER_REF_NO, merchantId: NEW_CLIENT_ID, partnerRefundNo: "RFND" + random, externalStoreId: EXTERNAL_STORE_ID, value: REFUND_AMOUNT, cancelType: CANCEL_TYPE, currency: REFUND_CURRENCY, reason : REASON ); string externalId = NEW_EXTERNAL_ID; string createResponse = await qrisService.SendPostRequest(apiEndpoints.RefundQris, accessToken, timestamp, createRequestBody, externalId); Console.WriteLine("Refund Qris Response: " + createResponse); ``` Laravel ```php protected $useProd = false; protected $useCloud = false; protected $refund_qris_endpoint = "/api/v1.0/qr/qr-mpm-refund"; // Credential protected $client_id = "IONPAYTEST"; PROTECTED $key = "_PRIVATE_KEY_MERCHANT"; PROTECTED $client_secret = "_CLIENT_SECRET_MERCHANT"; PROTECTED $access_token = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJJT05QQVlURVNUIiwiaXNzIjoiTklDRVBBWSIsIm5hbWUiOiJCUklOIiwiZXhwIjoiMjAyNC0wMi0xMVQwODowOTozNVoifQ==.aIybLX36dYwfFvW7dcoenXkOe2EAwIYq84ZtPuIf3K8="; PROTECTED $store_id = "NICEPAY"; $url = HttpUtil::getNicepayDomain($this->useProd, $this->useCloud) . $this->refund_qris_endpoint; $helper = new Helpers(); $http_method = "POST"; $x_time_stamp = "2024-12-31T10:11:40+07:00"; $partner_id = $this->client_id; $client_secret = $this->client_secret; $access_token = $this->access_token; $store_id = $this->store_id; $external_id = "eXid202402111402271707638098"; $channel_id = "IONPAYTEST"; $refundAmount = [ "value" => "10000.00", "currency" => "IDR" ]; $additionalInfo = [ "cancelType" => "1" ]; $body = [ "originalReferenceNo" => "ncpy20221017161458", "originalPartnerReferenceNo" => "IONPAYTEST08202106091121206416", "partnerRefundNo" => "ncpy20221017161458", "merchantId" => $partner_id, "externalStoreId" => $store_id, "refundAmount" => $refundAmount, "reason" => "Refund Trans", "additionalInfo" => $additionalInfo ]; $string_to_sign = $helper->generateStringToSign( $http_method, $this->refund_qris_endpoint, $access_token, $body, $x_time_stamp ); $signature = $helper->hmacSHA512Encoded( $string_to_sign, $client_secret, OPENSSL_ALGO_SHA512 ); $header = $helper->generateHeader( $access_token, $x_time_stamp, $signature, $partner_id, $external_id, $channel_id ); try { $response = HttpUtil::postJsonRequestWithHeader($url, $body, $header); } catch (Exception $e) { // Handle exception } ``` PHP Native ```php $config = NICEPay::builder() ->setIsProduction(false) ->setPrivateKey("_YOUR_PRIVATE_KEY_") ->setClientSecret("_YOUR_CLIENT_SECRET_") ->setPartnerId("IONPAYTEST") ->setExternalID("eXid202402111402271707638098") ->setTimestamp("2024-12-31T10:11:40+07:00") ->build(); $requestBody = Cancel::builder() ->setOriginalReferenceNo("ncpy20221017161458") ->setOriginalPartnerReferenceNo("IONPAYTEST08202106091121206416") ->setPartnerRefundNo("ncpy20221017161458") ->setMerchantId("IONPAYTEST") ->setExternalStoreId("NICEPAY") ->setRefundAmount("10000.00", "IDR") ->setReason("Refund Trans") ->setAdditionalInfo( ["cancelType" => "1"] ) ->build(); $accessToken = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJJT05QQVlURVNUIiwiaXNzIjoiTklDRVBBWSIsIm5hbWUiOiJCUklOIiwiZXhwIjoiMjAyNC0wMi0xMVQwODowOTozNVoifQ==.aIybLX36dYwfFvW7dcoenXkOe2EAwIYq84ZtPuIf3K8="; $qrisService = new SnapQrisService($config); $response = $qrisService->refund($requestBody, $accessToken); ``` ```kotlin const val ACCESS_TOKEN = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJJT05QQVlURVNUIiwiaXNzIjoiTklDRVBBWSIsIm5hbWUiOiJCUklOIiwiZXhwIjoiMjAyNC0wMi0xMVQwODowOTozNVoifQ==.aIybLX36dYwfFvW7dcoenXkOe2EAwIYq84ZtPuIf3K8=" // Step 1: Initialize the NICEPay Configuration var config: NICEPay = NICEPay.Builder() .isProduction(false) .clientSecret("YOUR_CLIENT_SECRET") .partnerId("IONPAYTEST") .externalID("eXid202402111402271707638098") .timestamp("2024-12-31T10:11:40+07:00") .privateKey("YOUR_PRIVATE_KEY") // Placeholder .build() // Step 2: Define the QRIS Refund Request Body val refundQris: SnapCancel = SnapCancel.Builder() .merchantId("IONPAYTEST") .originalPartnerReferenceNo("IONPAYTEST08202106091121206416") .originalReferenceNo("ncpy20221017161458") .partnerRefundNo("ncpy20221017161458") .externalStoreId("NICEPAY") .refundAmount("10000.00", "IDR") .reason("Refund Trans") .additionalInfo( mapOf( "cancelType" to "1" ) ) .build() // Step 3: Execute the Refund val response: NICEPayResponse? = snapQrisService.refund(refundQris, ACCESS_TOKEN, config) ``` CodeIgniter ```php $config = NICEPay::builder() ->setIsProduction(false) ->setIsCloudServer(isCloudServer: true) ->setPrivateKey("_YOUR_PRIVATE_KEY_") ->setClientSecret("_YOUR_CLIENT_SECRET_") ->setPartnerId("IONPAYTEST") ->setExternalID("eXid202402111402271707638098") ->setTimestamp("2024-12-31T10:11:40+07:00") ->build(); $requestBody = RefundQris::builder() ->setOriginalReferenceNo("ncpy20221017161458") ->setOriginalPartnerReferenceNo("IONPAYTEST08202106091121206416") ->setPartnerRefundNo("ncpy20221017161458") ->setMerchantId("IONPAYTEST") ->setExternalStoreId("NICEPAY") ->setRefundAmount("10000.00", "IDR") ->setReason("Refund Trans") ->setAdditionalInfo(["cancelType" => "1"]) ->build(); $accessToken = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJJT05QQVlURVNUIiwiaXNzIjoiTklDRVBBWSIsIm5hbWUiOiJCUklOIiwiZXhwIjoiMjAyNC0wMi0xMVQwODowOTozNVoifQ==.aIybLX36dYwfFvW7dcoenXkOe2EAwIYq84ZtPuIf3K8="; $snapQrisService = new SnapQrisService($config); try { $response = $snapQrisService->refund($requestBody, $accessToken, $config); } catch (\Exception $e) { // Handle exception } ``` ::: ### Response Parameter :::CodeblockTabs Sample Response ```json { "responseCode": "2007800", "responseMessage": "Successful", "originalReferenceNo": "IONPAYTEST082021017161458", "refundNo": "IONPAYTEST08202106091121206416", "partnerRefundNo": "ncpy20221017161458", "refundAmount": { "value": "10000.00", "currency": "IDR" }, "refundTime": "2022-07-20T07:15:00+07:00", "additionalInfo": { "cancelTrxSn": "07202210051341224326" } } ``` :::