Refund an order

Use this endpoint to issue a full or partial refund for a completed Hosted Model order.

Endpoint summary

Path: /hosted-checkout/refund
Method: POST
Content-Type: application/json

Request parameters

Parameter	Type	Mandatory	Description
merchantId	String	M	Merchant identifier
orderId	Number	C	Order ID of the payment. Mandatory when merchantReference is not given
merchantReference	String(64)	C	Unique reference of the order. Mandatory when orderId is not given
amount	Number(9,2)	M	Refund amount

note

• Refund supports both full and partial amounts but can only be performed once per order.
• BBMSL approves the refund only when your merchant account has sufficient unsettled balance.

Request example

{
    "request": "{\"merchantId\":3,\"orderId\":4922,\"amount\":10}",
    "signature": "oFkjUA2eEn2fSZHE5p8fzddO2dF7IfDwrmeZ4yBS5eVaMLjIeGwKwybPSl13PBEEhdwzRwWjVDFCk0AJvuzrE6C3udD0BsU8Yt7BMte/RFBQWTneKFpB/zkAM1QBKsb4slj8ZZ2BT3LutV1gGX89APAp/OeIjuy/NiporFo21LwCALK+B4JR/0zRXrQoBQLKdUEoL8eSEWo1vBISWf8/0Do/pi/6r18Mf91ghcYmGQDJBlJ2bG6whuEwM8serrpnwVgV1Liyqc5xqHhJ8eodF0IlOyiHlrMMdD88hyVaSqdSKfWb/OKhIl+6u3v4xeGxdnnZbQ9LZhBMeQWgBXwYDw=="
}

Response parameters

Parameter	Type	Mandatory	Description
responseCode	String	M	Payment Gateway response code
message	String	M	Payment Gateway response message
order	Object	M
order.id	Number	M	Order identifier
order.merchantId	Number	M	Merchant identifier which own this order
order.merchantReference	String	M	Your reference for the order
order.currency	String	M	3-Letters ISO currency code of the order
order.amount	Number	M	Order amount
order.netAmount	Number	M	Net amount of the order
order.cardType	String	M	Card type of the order
order.email	String	M	Customer's email if provided
order.createTime	Datetime	M	Timestamp when the order is created. Maintained by the Payment Gateway
order.updateTime	Datetime	M	Timestamp when the order is last updated. Maintained by the Payment Gateway
order.status	String	M	Status of the order. Maintained by the Payment Gateway
order.recurring	Boolean	M	Flags the order is a recurring order or not
transaction	Object	M
transaction.id	Number	M	Transaction identifier for the refund transaction
transaction.merchantId	Number	M	Merchant identifier which own this transaction
transaction.type	String	M	Transaction type
transaction.amount	Number	M	Refund transaction amount
transaction.status	String	M	Status of the transaction. Maintained by the Payment Gateway
transaction.maskedPan	String	M	Masked card number of the original sale transaction if supported by the payment method
transaction.stan	String	M	System trace audit number for the transaction

Response example

{
  "responseCode": "0000",
  "order": {
    "id": 4922,
    "merchantId": 3,
    "merchantReference": "1655817171",
    "currency": "USD",
    "amount": 15.00,
    "netAmount": 5.00,
    "cardType": "VISA",
    "email": "",
    "createTime": "2022-06-21T13:13:10.000+00:00",
    "updateTime": "2022-06-21T19:00:12.000+00:00",
    "status": "REFUNDED",
    "recurring": false
  },
  "transaction": {
    "id": 3758,
    "merchantId": 3,
    "type": "REFUND",
    "amount": 10,
    "currency": "USD",
    "status": "SUCCESS",
    "maskedPan": "400000XXXXXX0028",
    "stan": "S3142"
  }
}