Refunds API

Refund API

Purpose

If a payment was successful but the order was not fulfilled, the transaction amount is refunded to the customer by using the partner's refund API. As each partner has a unique refund processing time, the partner should provide acknowledgment (ACK) to confirm that the refund has been initiated for a specific transaction.

API Contract

Environment	Endpoint
UAT	https://bank.uat.com/payment-service/partner/refund
Production (CUG)	https://bank.prod.com/payment-service/partner/refund

Headers

• X-Body-Signature: Checksum (HMAC-SHA256), generated using the partner-secret-key.
• partner-key: <NUCLEI-SDK-KEY>

Request Body (Parameters)

• Request Structure:

  {
    "payload": "<encrypted message body AES>"
  }

• Message Body example (Decoded payload):

  {
    "transactionId": "N-AAAAAA-FUI9QWO-CAIVDEK",       // string <payment transaction id >
    "refundTransactionId": "N-HBA14RA-FUI9QWO-CAIVDEK",  // string
    "orderId": "N-FFKKKRA-FUI9QWO-CAIVDEE",              // string
    "refundAmount": "100",                               // string 
    "requestDate": "20170911115412"                      // string 
  }

Response Body (from Partner)

• Response Structure:

  {
    "payload": "<encrypted message body AES>"
  }

• Message Body example (Decoded payload):

  {
    "refundStatus": "ACK",                               // string
    "refundTransactionId": "N-HBA14RA-FUI9QWO-CAIVDEK",  // string
    "bankReferenceNumber": "ZREF0123456ABC",             // string
    "errorMessage": "NA",                                // string
    "statusCode": "00"                                   // string
  }

Status Codes and Descriptions

• statusCode:

  • "00": Success
  • "01": Error

• refundStatus:

  • SUCCESS: Refund successful
  • FAILURE: Refund failed
  • ACK: Refund process acknowledged (interpreted as IN-PROGRESS)
  • NOT FOUND: Transaction not found