Refund of a payment is marked as a cancel for certain situations and a refund for other certain situations.
CANCEL: If the refund request is made on the same day the payment was made and there is no partial refund of this payment previously made,
while responding, refundType returns CANCEL, id information exists and the paymentTransactionRefunds list is empty.
REFUND: If a partial refund has been made before, or if the refund request is made on a different day than the day the payment was made,
while responding, refundType returns REFUND, id information does not exist and paymentTransactionRefunds list is full
(includes information about each partial refund).
The endpoint and http method information to refund a payment are stated below.
| HTTP Method | URL |
|---|---|
POST |
/payment/v1/refunds |
The parameters expected to be sent in the requests to be made to refund are listed under the table and sub-headings below.
| Parameter Name | Type | Required | Description |
|---|---|---|---|
paymentId |
number |
Yes | ID of the payment that that requested to be refunded |
conversationId |
string |
No | "boomerang" value that can be sent with the request and received with the response. It can be used to associate different requests with each other. Usually, the order number is used that is stored in merchant own system. |
refundDestinationType |
RefundDestinationType |
No | See: Refund Type |
chargeFromMe |
boolean |
No | Should the refund is charged by using merchant's balance? Can be used in case of insufficient sub-merchant balance in marketplace payment |
| Parameter Name | Type | Description |
|---|---|---|
id |
number |
ID of the refund |
conversationId |
string |
Value of theconversationId parameter sent in the payment initiation request |
createdDate |
date |
The date that the payment is refunded |
status |
string |
See: Refund Status Type |
refundPrice |
decimal |
Price of the refund |
refundBankPrice |
decimal |
Bank price of the refund |
refundWalletPrice |
decimal |
Wallet price of the refund |
refundType |
string |
Returns CANCEL if cancelled and REFUND if refunded |
refundDestinationType |
RefundDestinationType |
See: Refund Type |
authCode |
string |
authCode value retrieved from bank for the refund |
hostReference |
string |
hostReference value retrieved from bank for the refund |
transId |
string |
transId value retrieved from bank for the refund |
currency |
Currency |
Currency of the refund. See: Currencies |
paymentId |
number |
ID of the payment of to be refunded |
paymentTransactionRefunds |
PaymentTransactionRefundResponse[] |
See: Payment Transaction Refund Information |
It is the object that contains information about the transaction of the refunded payment
| Parameter Name | Type | Description |
|---|---|---|
id |
number |
ID of the transaction refund |
conversationId |
string |
Value of theconversationId parameter sent in the payment initiation request |
createdDate |
date |
The date that the payment transaction is refunded |
status |
string |
See: Refund Status Type |
isAfterSettlement |
boolean |
Returns true if payment transaction is refunded after settlement |
refundPrice |
decimal |
Price of the transaction refund |
refundBankPrice |
decimal |
Bank price of the transaction refund |
refundWalletPrice |
decimal |
Wallet price of the transaction refund |
currency |
Currency |
Currency of the transaction refund. See: Currencies |
paymentTransactionId |
number |
ID of the payment transaction to be refunded |
paymentId |
number |
ID of the payment to be refunded |
refundDestinationType |
RefundDestinationType |
See: Refund Type |
You can review the sample codes in the open source Craftgate API clients.