# Refund payment (payment reversal)

`POST /v2/payments/reversal`

**Base URLs:**

- Sandbox: `https://api.sandbox.bobpay.co.za`
- Production: `https://api.bobpay.co.za`

**Authentication:** Bearer token required. Obtain one via `POST /login` (see the Authentication page).

## Example request

```bash
curl -X POST "https://api.sandbox.bobpay.co.za/v2/payments/reversal" \
  -H "content-type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
    "id": 72052
}'
```

This endpoint enables you to initiate a 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

| Key | Description | Type | Required |
| --- | --- | --- | --- |
| id | ID of the payment record to refund. | integer | Conditional* |
| custom_payment_id | Your custom identifier for the payment to refund. | string | Conditional* |
| payment_method_id | Payment method record ID, used together with `payment_method`. | integer | Conditional* |
| payment_method | The payment method of the payment, used together with `payment_method_id`. | string | Conditional* |
| reversal_amount | The amount to refund, for partial refunds. Must be greater than zero and may not exceed the payment amount. Defaults to the full payment amount. | float | No |
| reverse_directly_to_bank | If true, the funds are reversed directly to the payer's bank instead of their Bob Pay account balance. Only supported for certain payment methods (e.g., card payments, Scan to Pay, Capitec Pay). Defaults to `true` for payment methods that support it; set to `false` to refund to the payer's Bob Pay account balance instead. | boolean | No |

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

**Example:**

```json
{
    "id": 72052
}
```

---

### Response

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

---

#### Response body

```json
{
    "payment_method": {
        "id": 1186,
        "payment_intent_id": 114092,
        "payment_intent_reference": "3R3PW",
        "account_id": 377,
        "account": {
            "id": 377,
            "name": "Auto-generated account",
            "account_code": "AUT065",
            "signup_name": null,
            "is_merchant": false
        },
        "recipient_account_id": 370,
        "recipient_account": {
            "id": 370,
            "name": "Bob shop",
            "account_code": "BOB010",
            "signup_name": "Sandbox User",
            "merchant_start_date": "2024-11-29T11:06:28.425924+02:00",
            "is_merchant": true
        },
        "amount": 5,
        "status": "refunded",
        "transaction_date": "2025-07-17T11:47:23.321682+02:00",
        "type": "payment",
        "time_created": "2025-07-17T11:47:23.323953+02:00",
        "time_modified": "2025-07-17T11:47:39.619253+02:00",
        "custom_payment_id": "13840594",
        "jurisdiction": "Local",
        "card_association": "VISA",
        "is_debit_card": false
    },
    "reversed_directly_to_bank": true
}
```

---

#### Response fields

| Key | Description | Type |
| --- | --- | --- |
| payment_method | Object with details about the reversed payment. | object |
| payment_method.id | Unique payment record ID. | integer |
| payment_method.payment_intent_id | Payment intent ID linked to this payment. | integer |
| payment_method.payment_intent_reference | Short payment intent reference. | string |
| payment_method.account_id | Originating account ID. | integer |
| payment_method.account | Object with originating account details. | object |
| payment_method.recipient_account_id | Recipient account ID. | integer |
| payment_method.recipient_account | Object with recipient account details. | object |
| payment_method.amount | Amount refunded. | float |
| payment_method.status | Status of the refund (should be "refunded"). | string |
| payment_method.transaction_date | Transaction date and time. | string (date) |
| payment_method.type | Type of transaction (e.g., "payment"). | string |
| payment_method.time_created | Time created. | string (date) |
| payment_method.time_modified | Time last modified. | string (date) |
| payment_method.custom_payment_id | Custom payment identifier. | string |
| payment_method.jurisdiction | Payment jurisdiction. | string |
| payment_method.card_association | Card association (e.g., VISA). | string |
| payment_method.is_debit_card | True if debit card used. | boolean |
| reversed_directly_to_bank | True if funds were reversed directly to bank. | boolean |

**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.