Refund payment (payment reversal)

This endpoint enables you to initiate a full or partial refund for a specific payment. It allows you to process payment reversals efficiently, ensuring that refunds are handled seamlessly.

Request

Method: POST URL: https://api.sandbox.bobpay.co.za/v2/payments/reversal

Request body parameters

* Note: Identify the payment using one of id, custom_payment_id, or payment_method_id together with payment_method.

Example:

{
    "id": 72052
}

Partial refunds

Partial refunds are supported. Send reversal_amount with the amount you want to refund — that is the only additional field required. Identify the payment exactly as you would for a full refund. Leave reversal_amount out to refund the full amount.

{
    "id": 72052,
    "reversal_amount": 50.00
}

Rules

• reversal_amount must be greater than zero and may not exceed the original payment amount, or the amount still outstanding if the payment is already partially_refunded.
• The payment must have a status of success or partially_refunded. A payment that is already refunded cannot be refunded again.
• After the first partial refund, the payment and its payment intent move to partially_refunded.
• Once the partial refunds together add up to the full payment amount, the payment and its payment intent move to refunded.
• Your account balance must cover the refund amount plus the reversal fee.
• Test payments and account top-up payments cannot be refunded.

Second and later refunds

Only one refund per payment can be sent back to the payer's bank or card. On any refund after the first, set reverse_directly_to_bank to false so that the refund is credited to the payer's Bob Pay account balance.

{
    "id": 72052,
    "reversal_amount": 50.00,
    "reverse_directly_to_bank": false
}

If you leave reverse_directly_to_bank out, it defaults to true for card, Apple Pay, Google Pay and Capitec Pay payments, and the request fails with cannot reverse a <payment method> payment more than once.

Scan to Pay is the exception: it accepts more than one refund to the payer's bank, but only within 72 hours of the payment. After 72 hours the refund is credited to the payer's Bob Pay account balance instead. Check reversed_directly_to_bank in the response to confirm where the funds were sent.

Refunds that complete asynchronously

For Scan to Pay and Capitec Pay refunds to bank, the refund is confirmed by the bank after the request returns. The payment moves to refund_pending first, and then to its final refunded status once the bank confirms the refund. Capitec Pay accepts only one refund per payment.

Response

Status code: 200 OK Content-Type: application/json

Response fields

Note:

• The fields of the payment_method object depend on the payment method being refunded. The example above shows a card refund; fields such as jurisdiction, card_association, and is_debit_card are card-specific.
• The response also contains deprecated PaymentMethod and ReversedDirectlyToBank keys (duplicates of payment_method and reversed_directly_to_bank). Ignore these; they will be removed in a future version.

Common errors

All of the errors below are returned with status code 400.