Cancellation and Refund
Overview
If you want to cancel a payment, you can perform one of two operations depending on the payment status: cancellation or refund. Cancellation is possible until the money is captured by the Bank. When the money are already captured, only the refund can be made.
These operations are described below.
Cancellation
Cancellation is possible until the money is captured by the Bank. Two types of cancellation can be made depending on your payment flow.
Expire Session
If you use a payment page on the Payment Gateway side, a Session is created for payment. In this case, you can expire this Session if it has "open" status (the Session is created and ready for payment). After the Session expires, it gets the "expired" status and no further processing is possible. You will receive session.expired webhook.
To expire the session, use the /sessions/id/expire POST request. See the detailed description of the request in the API Reference.
Request example:
curl -X POST "https://dev.bpcbt.com/api2/sessions/ps_2GRSigkh7nHdxwjV4Yf7PpdEevc1dAwEvssZuP8TJ6mjuNmPMoV9mB/expire" \
-H "X-Api-Key: 6HUXQFbeomV1zf5i8cgm5W8KfncENVEa5uh8RngB" \
-H "X-Version: 2023-10-31" \
Response example:
{
"id": "ps_2GRSigkh7nHdxwjV4Yf7PpdEevc1dAwEvssZuP8TJ6mjuNmPMoV9mB",
"amount": 20000,
"created": "2024-03-29T05:33:26Z",
"currency": "eur",
"customerDetails": {},
"expiresAt": "2024-03-29T05:53:26Z",
"failureUrl": "https://mybestmerchantreturnurl.com/failure",
"locale": "EN",
"merchantReferenceId": "4002",
"metadata": {},
"paymentData": {
"captureMethod": "automatic"
},
"paymentStatus": "unpaid",
"status": "expired",
"successUrl": "https://mybestmerchantreturnurl.com/success"
}
Cancel Payment
If you use a payment page on your side, a Payment object is created for payment. In this case, you can cancel a Payment before the first capture is done. The Payment should be in one of the following statuses:
- "requiresPaymentMethod"
- "requiresCapture"
- "requiresAction"
After cancellation, the Payment gets "canceled" status. You will receive payment.canceled webhook.
If the Payment in "requiresCapture" status is cancelled, the rest of pre-authorized amount (the amountCapturable value) is automatically returned to the customer.
To cancel a Payment, use the /payments/id/cancel POST request. See the detailed description of the request in the API Reference.
Request example:
curl -X POST "https://dev.bpcbt.com/api2/payments/p_HbtjsyScZawhNKxmLPTFP3PDHmFq1B5BAZZ5mx8SP3wSMzVzwWob/cancel" \
-H "X-Api-Key: 6HUXQFbeomV1zf5i8cgm5W8KfncENVEa5uh8RngB" \
-H "X-Version: 2023-10-31" \
Response example:
{
"id": "p_HbtjsyScZawhNKxmLPTFP3PDHmFq1B5BAZZ5mx8SP3wSMzVzwWob",
"amount": 10000,
"amountCapturable": 0,
"amountReceived": 0,
"canceledAt": "2024-03-29T08:21:55Z",
"captureMethod": "automatic",
"created": "2024-03-29T08:09:17Z",
"currency": "eur",
"customerDetails": {
"address": {
"city": "Test city",
"country": "CY",
"line1": "Test address1",
"line2": "Test address2",
"postalCode": "Test postal code",
"state": "Test state"
},
"email": "test@example.com",
"name": "TEST CARDHOLDER",
"phone": "+449998887766"
},
"description": "Some description",
"merchantCustomerId": "123",
"metadata": {},
"paymentMethod": {
"card": {
"expiryMonth": 12,
"expiryYear": 2024,
"holderName": "TEST CARDHOLDER",
"maskedNumber": "411111**1111"
},
"type": "card"
},
"paymentMethodOptions": {
"card": {
"threeDSecureMode": "automatic",
"verify": true
}
},
"returnUrl": "https://mybestmerchantreturnurl.com/",
"setupFutureUsage": {
"category": "unscheduled"
},
"status": "canceled"
}
Refund
Refund means returning already captured funds to the customer. This operation can be applied to one-step or two-step Payments when the funds are already captured ("succeeded" status of the Payment object).
After the refund, the Payment remains in the "succeeded" status and the Session (if it was used) remains in the "completed" status. Additionally, after the refund, you will receive refund.updated webhook.
You can make refund more than once, but for a total amount not exceeding the initial captured amount.
To create a refund, use the /refunds POST request. See the detailed description of the request in the API Reference.
Request example:
curl -X POST "https://dev.bpcbt.com/api2/refunds" \
-H "X-Api-Key: 6HUXQFbeomV1zf5i8cgm5W8KfncENVEa5uh8RngB" \
-H "X-Version: 2023-10-31" \
-H "Content-Type: application/json" \
-d '{
"amount": 70000,
"paymentId": "p_HbtjsyTuig5SWYufjsFeTNAX3WisQFUSvbroA1C48Y5XN8Pstcdw"
}'
Response example:
{
"amount": 70000,
"created": "2024-03-31T23:52:06Z",
"currency": "eur",
"id": "re_PCPaoQPuTeE293WF2Usq9enFQwVLwV5Kkz5uA9L52fYiDiTw8cmas5HhLMEaSzkEDuiMmPtbyZZnMZYqFbkw44ihSGRPEiL1F",
"paymentId": "p_HbtjsyTuig5SWYufjsFeTNAX3WisQFUSvbroA1C48Y5XN8Pstcdw",
"status": "succeeded"
}
Additionally, you can retrieve the details of an existing refund using the /refunds/{id} request and retrieve a list of all refunds for a particular Payment using the /payments/{id}/refunds request.