---
title: "MPGS Card - ZA Connector"
source_url: https://docs.rapyd.net/en/mpgs-card---za-connector.html
lang: en
---

# MPGS Card - ZA Connector

### Connector overview

- **Connector name:** MPGS Card - ZA
- **Payment method type:** `za_mpgsvisa_card` (Visa in South Africa - Visa card payments in ZAR processed through MPGS (category card, flow card).); `za_mpgsmastercard_card` (Mastercard in South Africa - Mastercard card payments in ZAR processed through MPGS (category card, flow card).)
- **Gateway name:** MPGS (Mastercard Payment Gateway Services) - Rapyd gateway mpgs_za
- **Supported countries and currencies:** South Africa (ZA), ZAR
- **Gateway**: Mastercard Payment Gateway Services (MPGS) REST API v100, direct server-to-server card API. No hosted checkout or redirect from MPGS itself.
- Rapyd acts as the aggregator on MPGS. Every PAY, AUTHORIZE and VERIFY sends sub-merchant details (order.subMerchant) that must pass Mastercard merchant data quality rules.

### Capabilities

| API request | Endpoint | Unique capabilities | Limitations |
| --- | --- | --- | --- |
| Create payment (card) | `POST /v1/payments` | capture=true sends MPGS PAY (payment closes immediately, status **CLO**). capture=false sends AUTHORIZE (status **ACT**, capture later). amount 0 with capture=false sends VERIFY (card check). Rapyd 3DS result (CAVV/ECI/3DS2 data) is forwarded to MPGS. Stored credentials: initiation_type customer_present/moto/recurring/installment/unscheduled maps to MPGS CIT/MIT agreement fields. Network tokens (TPAN + cryptogram) are sent as MPGS SCHEME_TOKEN. Apple Pay / Google Pay decrypted cards are sent with walletProvider and the device cryptogram. Acquirer response code and message are returned as failure_code / failure_message on declines. | ZAR only; sub-merchant data must pass Mastercard MDQ checks. |
| Create payment - Account Funding Transaction (AFT) | `POST /v1/payments` | payment_method_options.aft=true sends an MPGS PAY with order.purchaseType=ACCOUNT_FUNDING and an accountFunding block (purpose, senderType PERSON, senderIsRecipient true, recipient = the Rapyd wallet being funded). Supports both Rapyd AFT flows: C2C (cardholder's own wallet) and C2C_PSP (merchant's client wallet). Visa purposeOfPayment IS codes, Mastercard crypto / high-risk-securities trading purposes, and direct purchase (is_direct_purchase) as order.purchaseType CRYPTOCURRENCY / HIGH_RISK_SECURITIES. Pre-flight checks reject bad MCC / scenario combinations with failure_code AFT_VALIDATION_FAILED and a readable message. | Must be enabled for the merchant; supported MCCs only. |
| Capture payment | `POST /v1/payments/{payment}/capture` | Full or partial capture of an AUTHORIZE (MPGS CAPTURE on the same order). The connector checks the amount does not exceed the remaining authorized amount. Sends order.expectedNumberOfCaptures (default 1 from the payment options). | Only one capture is expected by default. |
| Cancel payment (void) | `DELETE /v1/payments/{payment}` | Voids an open authorization (MPGS VOID with targetTransactionId = original transaction). Payment status becomes **CAN**. | Only for authorized, not yet captured payments. |
| Create refund | `POST /v1/refunds` | Full and partial refunds (MPGS REFUND on the original order). Approved = refund closed; PENDING/SUBMITTED/UNKNOWN = refund pending; declines return the acquirer code/message. AFT refunds carry order.purchaseType=ACCOUNT_FUNDING. | Visa AFT funding transactions cannot be refunded. |
| Retrieve payment | `GET /v1/payments/{payment}` | The connector implements getPayment / pollingUpdate using MPGS Retrieve Transaction (GET) and re-syncs the status. Polling also voids an authorization that is past Rapyd's expiration time. | Polling is scheduler-driven, not merchant-triggered. |

- **Header parameters:** Standard Rapyd [headers](https://docs.rapyd.net/en/header-parameters.md "Header Parameters"). No connector-specific headers.
- **Supported workflows**

  - [Card payments](https://docs.rapyd.net/en/card-payments.md "Card Payments"): direct card, capture true/false, 3DS via Rapyd.
  - Authorize then capture, partial capture, void and refund on the same card payment.
  - Zero-amount card verification (amount 0, capture=false) sent to MPGS as VERIFY.
  - Stored credentials / recurring: customer-initiated first payment stores an agreement (save_payment_method), later merchant-initiated payments reference it (initiation_type recurring/installment/unscheduled).
  - Network token (scheme token) payments with cryptogram; Apple Pay and Google Pay decrypted card payments.
  - Account Funding Transactions (wallet top-up by card) for Rapyd C2C and C2C_PSP AFT flows - ZA only.

### Field mapping tables

### Create Payment - Body parameters

> **Note:**
>
> This table has many columns. Use the horizontal scroll bar below the table to move across and view all of the columns.

| Field name | Parent field | Data type | Required or optional | Default value | Accepted values (enum) | Constraints | Description | Example | Provided by |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `amount` | - | number | Required | - | - | Decimal amount in major units. 0 allowed only with capture=false (card verification). | Payment amount. | 150.00 | Merchant |
| `currency` | - | string | Required | - | **ZAR** | - | ISO 4217 currency code. | ZAR | Merchant |
| `payment_method` | - | object | Required | - | - | - | Card payment method object. | {...} | Merchant |
| `type` | `payment_method` | string | Required | - | **`za_mpgsvisa_card`**, **`za_mpgsmastercard_card`** | - | Payment method type. | `za_mpgsvisa_card` | Merchant |
| `number` | `payment_method.fields` | string | Required | - | - | - | Card number (PAN), or token PAN when number_type=tpan. | 5123450000000008 | Merchant |
| `expiration_month` | `payment_method.fields` | string | Required | - | **01-12** | - | Card expiry month. | 01 | Merchant |
| `expiration_year` | `payment_method.fields` | string | Required | - | - | Two digits | Card expiry year. | 39 | Merchant |
| `cvv` | `payment_method.fields` | string | Required | - | - | - | Card security code. | 100 | Merchant |
| `name` | `payment_method.fields` | string | Optional | - | - | - | Cardholder name. | Test Cardholder | Merchant |
| `number_type` | `payment_method.fields` | string | Optional | - | **fpan**, **tpan** | - | Whether number is a funding PAN or a network token PAN. | fpan | Merchant |
| `network_reference_id` | `payment_method.fields` | string | Optional | - | - | - | Scheme network transaction reference from a previous payment. | - | Merchant |
| `recurrence_type` | `payment_method.fields` | string | Optional | - | **recurring**, **installment**, **unscheduled** | - | How a stored card will be used. | recurring | Merchant |
| `tavv` | `payment_method.fields` | string | Conditional | - | - | Base64, 20-byte value | Token cryptogram for network token payments. | AAAAAAAAAAAAAAAAAAAAAAAAAAA= | Merchant |
| `capture` | - | boolean | Optional | true | **true**, **false** | - | true = authorize and capture now (MPGS PAY). false = authorize only (MPGS AUTHORIZE), capture later. | true | Merchant |
| `3d_required` | `payment_method_options` | boolean | Optional | - | **true**, **false** | - | Ask for 3DS authentication. | true | Merchant |
| `initiation_type` | `payment_method_options` | string | Optional | - | **customer_present**, **installment**, **moto**, **recurring**, **unscheduled** | - | How the payment was initiated (stored credentials). | customer_present | Merchant |
| `save_payment_method` | - | boolean | Optional | false | - | - | Keep the card agreement for later merchant-initiated payments. | false | Merchant |
| `original_payment` | - | string | Conditional | - | - | - | Rapyd payment id of the payment that first stored the card (MIT). | payment_0f0e0d0c0b0a09080 | Merchant |
| `complete_payment_url` | - | string | Conditional | - | - | - | Where the customer returns after Rapyd 3DS. | https://merchant.example.com/success | Merchant |
| `error_payment_url` | - | string | Conditional | - | - | - | Where the customer returns if 3DS fails. | https://merchant.example.com/error | Merchant |
| `merchant_reference_id` | - | string | Optional | - | - | - | Merchant's own order reference. | ORDER-2026-000123 | Merchant |
| `description` | - | string | Optional | - | - | - | Payment description. | 2 x Widget + shipping | Merchant |
| `statement_descriptor` | - | string | Optional | - | - | - | Merchant name on the card statement. | MYSHOP | Merchant |
| `sub_merchant_details` | `metadata` | object | Optional | - | - | - | Sub-merchant details for aggregator transactions. | {"trading_name":"MYSHOP",...} | Merchant |
| `agreement_details` | `metadata` | object | Optional | - | - | - | Recurring agreement settings for a customer-initiated first payment. | {"agreement_expiry":"2027-12-31","amount_variability":"FIXED","number_of_payments":12} | Merchant |
| `aft` | `payment_method_options` | boolean | Optional | false | - | - | Process as an Account Funding Transaction. | true | Merchant |
| `purpose_code` | `payment_method_options` | string | Conditional | - | - | - | AFT purpose. Required by Rapyd when aft=true. | family_support | Merchant |
| `is_direct_purchase` | `payment_method_options` | boolean | Optional | - | - | - | AFT direct purchase (crypto or high-risk securities). | false | Merchant |
| `special_condition_indicator` | `payment_method_options` | string | Optional | - | **cryptocurrency**, **stablecoin**, **central_bank_digital_currency**, **blockchain** | - | Crypto indicator for AFT direct purchase. | cryptocurrency | Merchant |
| `ewallet` | - | string | Conditional | - | - | - | Rapyd wallet being funded (AFT). | ewallet_1a2b3c4d5e6f | Merchant |
| `customer` | - | string or object | Conditional | - | - | - | Customer (sender) for AFT. | cus_1a2b3c4d5e6f | Merchant |
| `address` | - | object | Conditional | - | - | - | Sender billing address (AFT). | {"line_1":"1 Long Street","city":"Cape Town","country":"ZA"} | Merchant |
| `eci / cavv / xid / 3d_version / ds_trans_id / trans_status / transaction_reason_code` | `payment_method_options` | string | Optional | - | - | - | Externally supplied 3DS or wallet authentication data. | 05 | Merchant |

### Create Payment - Response parameters

> **Note:**
>
> This table has many columns. Use the horizontal scroll bar below the table to move across and view all of the columns.

| Field name | Parent field | Data type | Values (enum) | Description | Example | Provided by |
| --- | --- | --- | --- | --- | --- | --- |
| `id` | - | string | - | Rapyd payment id. Also used as the MPGS order id. | payment_1a2b3c4d5e6f7a8b9c0d | Rapyd |
| `status` | - | string | **ACT**, **CLO**, **ERR**, **CAN** | Payment status. | CLO | Gateway |
| `failure_code` | - | string | - | Reason code on failure. | 05 | Gateway |
| `failure_message` | - | string | - | Readable failure reason. | Do not honour | Gateway |
| `redirect_url` | - | string | - | 3DS challenge URL. | https://sandboxcheckout.rapyd.net/3ds-payment?token=payment_... | Rapyd |
| `captured` | - | boolean | - | Whether the payment is captured. | true | Rapyd |
| `acs_check` | `payment_method_data` | string | **pass**, **fail**, **unavailable** | 3DS result. | pass | Rapyd |
| `last4 / name / expiration_month / expiration_year` | `payment_method_data` | string | - | Masked card details. | 0008 | Rapyd |
| `original_amount / amount` | - | number | - | Amount requested / captured. | 150.00 | Rapyd |
| `merchant_reference_id` | - | string | - | Echo of the merchant reference. | ORDER-2026-000123 | Carried over |
| `payment_method_type` | - | string | **`za_mpgsvisa_card`**, **`za_mpgsmastercard_card`** | Payment method type used. | `za_mpgsvisa_card` | Carried over |
| `gateway reference (internal)` | - | string | - | MPGS order id stored as the payment gateway token. | payment_1a2b3c4d5e6f7a8b9 | Gateway |
| `auth_code` | - | string | - | Issuer authorization code. | - | Gateway |

### Capture Payment - Body parameters

> **Note:**
>
> This table has many columns. Use the horizontal scroll bar below the table to move across and view all of the columns.

| Field name | Parent field | Data type | Required or optional | Default value | Accepted values (enum) | Constraints | Description | Example | Provided by |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `payment` | `path` | string | Required | - | - | - | Id of the authorized payment. | payment_1a2b3c4d5e6f7a8b5c6d | Merchant |
| `amount` | - | number | Optional | Full authorized amount | - | Greater than 0 and not more than the remaining authorized amount | Amount to capture. | 100.00 | Merchant |
| `expected_number_of_captures` | `payment_method_options` | number | Optional | 1 | - | number >= 1, invalid values become 1 | Planned number of captures. | 1 | Merchant |

### Capture Payment - Response parameters

> **Note:**
>
> This table has many columns. Use the horizontal scroll bar below the table to move across and view all of the columns.

| Field name | Parent field | Data type | Values (enum) | Description | Example | Provided by |
| --- | --- | --- | --- | --- | --- | --- |
| `status` | - | string | **CLO**, **ACT**, **ERR** | CLO when MPGS result is SUCCESS (full or partial). ACT if MPGS is pending. ERR on failure. | CLO | Gateway |
| `captured / amount` | - | boolean / number | - | Captured flag and amount. | 100.00 | Gateway |
| `failure_code / failure_message` | - | string | - | Failure reason. | DECLINED | Gateway |

### Cancel Payment - Body parameters

> **Note:**
>
> This table has many columns. Use the horizontal scroll bar below the table to move across and view all of the columns.

| Field name | Parent field | Data type | Required or optional | Default value | Accepted values (enum) | Constraints | Description | Example | Provided by |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `payment` | `path` | string | Required | - | - | - | Id of the authorized payment to void. | payment_1a2b3c4d5e6f7a8b9c0d | Merchant |

### Cancel Payment - Response parameters

> **Note:**
>
> This table has many columns. Use the horizontal scroll bar below the table to move across and view all of the columns.

| Field name | Parent field | Data type | Values (enum) | Description | Example | Provided by |
| --- | --- | --- | --- | --- | --- | --- |
| `status` | - | string | **CAN**, **ACT**, **ERR** | CAN when MPGS approves the void; ACT if pending; ERR on failure. | CAN | Gateway |
| `failure_code / failure_message` | - | string | - | Failure reason. | INVALID_REQUEST | Gateway |

### Create Refund - Body parameters

> **Note:**
>
> This table has many columns. Use the horizontal scroll bar below the table to move across and view all of the columns.

| Field name | Parent field | Data type | Required or optional | Default value | Accepted values (enum) | Constraints | Description | Example | Provided by |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `payment` | - | string | Required | - | - | - | Id of the captured payment. | payment_1a2b3c4d5e6f7a85c6d | Merchant |
| `amount` | - | number | Optional | Full captured amount | - | - | Refund amount; partial allowed. | 100.00 | Merchant |
| `merchant_reference_id` | - | string | Optional | - | - | - | Merchant refund reference. | REFUND-000123 | Merchant |
| `reason` | - | string | Optional | - | - | - | Refund reason. | Customer request | Merchant |

### Create Refund - Response parameters

> **Note:**
>
> This table has many columns. Use the horizontal scroll bar below the table to move across and view all of the columns.

| Field name | Parent field | Data type | Values (enum) | Description | Example | Provided by |
| --- | --- | --- | --- | --- | --- | --- |
| `id` | - | string | - | Rapyd refund id. | refund_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d | Rapyd |
| `status` | - | string | **Completed**, **Pending**, **Error** | Refund status. | Completed | Gateway |
| `failure_reason` | - | string | - | Failure text. | Visa does not allow refunds on Account Funding Transactions... | Gateway |
| `failure_code` | - | string | - | Failure code. | AFT_REFUND_NOT_SUPPORTED | Gateway |
| `amount / currency / payment` | - | number / string | - | Refund amount, currency and payment id. | 100.00 | Carried over |

### Retrieve Payment - Path parameters

> **Note:**
>
> This table has many columns. Use the horizontal scroll bar below the table to move across and view all of the columns.

| Field name | Parent field | Data type | Required or optional | Default value | Accepted values (enum) | Constraints | Description | Example | Provided by |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `payment` | `path` | string | Required | - | - | - | Rapyd payment id. | payment_1a2b3c4d5e6f7a8 | Merchant |

### Retrieve Payment - Response parameters

> **Note:**
>
> This table has many columns. Use the horizontal scroll bar below the table to move across and view all of the columns.

| Field name | Parent field | Data type | Values (enum) | Description | Example | Provided by |
| --- | --- | --- | --- | --- | --- | --- |
| `status` | - | string | **ACT**, **CLO**, **ERR**, **CAN** | Current payment status. | CLO | Gateway |

### Migrating from PayU

This section shows how PayU Africa (Magellan API) fields, values and behavior relate to the Rapyd fields in the field mapping tables.

### Field mapping (Rapyd field to original PayU field)

### Create Payment - Body parameters

| Rapyd field name | Original PayU field |
| --- | --- |
| `amount` | CREDITCARD: `Basket.amountInCents` |
| `currency` | CREDITCARD: `Basket.currencyCode` (fallback: merchant config `currency.default`) |
| `payment_method` | CREDITCARD: `Creditcard` block |
| `type` | CREDITCARD (no field: The PMT is resolved from the instrument CREDITCARD, the merchant processor country `default.processor.country.code` and the card brand from the BIN) |
| `number` | CREDITCARD: `Creditcard.cardNumber` |
| `expiration_month` | CREDITCARD: `Creditcard.cardExpiry` (month part, split by `AfricaCardExpiryUtility`) |
| `expiration_year` | CREDITCARD: `Creditcard.cardExpiry` (year part, four-digit year converted to two) |
| `cvv` | CREDITCARD: `Creditcard.cvv` |
| `name` | CREDITCARD: `Creditcard.nameOnCard` |
| `number_type` | - |
| `network_reference_id` | - |
| `recurrence_type` | - |
| `tavv` | - |
| `capture` | CREDITCARD: `TransactionType` (PAYMENT = capture true, RESERVE = capture false) |
| `3d_required` | CREDITCARD: `AdditionalInformation.secure3d` (fallback: merchant config `3DSecure.enabled`) |
| `initiation_type` | CREDITCARD: `Customfield` key `cardEntryMode` (cof_consent_transaction, recurring_consent_transaction, cof_cardholder_initiated_transaction -> customer_present; cof_merchant_initiated_transaction -> unscheduled; recurring_subsequent_transaction -> recurring) |
| `save_payment_method` | CREDITCARD: `AdditionalInformation.storePaymentMethod` (also set when `Customfield` `processingType`=REAL_TIME_RECURRING and config `tokenize.paymentmethod`=true) |
| `original_payment` | CREDITCARD: `Creditcard.pmId` |
| `complete_payment_url` | CREDITCARD: `AdditionalInformation.returnUrl` |
| `error_payment_url` | CREDITCARD: `AdditionalInformation.returnUrl` (same value as `complete_payment_url`) |
| `merchant_reference_id` | CREDITCARD: `AdditionalInformation.merchantReference` (required, else P006) |
| `description` | CREDITCARD: `Basket.description` |
| `statement_descriptor` | - |
| `sub_merchant_details` | - |
| `agreement_details` | - |
| `aft` | - |
| `purpose_code` | - |
| `is_direct_purchase` | - |
| `special_condition_indicator` | - |
| `ewallet` | - |
| `customer` | Card: no inline customer; on a stored-card or MIT payment the existing Rapyd customer resolved from the `pmId` is linked |
| `address` | - |
| `eci / cavv / xid / 3d_version / ds_trans_id / trans_status / transaction_reason_code` | CREDITCARD: `Secure3DInfo.cavv` / `eciRaw` / `version` (1 -> 1.0.2, 2 -> 2.2.0) / `transactionId` (external 3DS; `cavv` and `eciRaw` both required) |

### Accepted values mapping

| Field name | Original PayU value | Rapyd value |
| --- | --- | --- |
| `capture` | TransactionType=PAYMENT | capture=true |
| `capture` | TransactionType=RESERVE | capture=false |
| `3d_required` | AdditionalInformation.secure3d=true | payment_method_options.3d_required=true |
| `amount` | Basket.amountInCents=15000 | amount=150.00 |
| `expiration_month / expiration_year` | Creditcard.cardExpiry=012039 | expiration_month=01, expiration_year=39 |
| `initiation_type` | Customfield cardEntryMode=cof_merchant_initiated_transaction | initiation_type=unscheduled |
| `initiation_type` | Customfield cardEntryMode=recurring_subsequent_transaction | initiation_type=recurring |
| `initiation_type` | cardEntryMode cof_consent_transaction / recurring_consent_transaction / cof_cardholder_initiated_transaction / absent | initiation_type=customer_present |
| `payment_method.type` | **CREDITCARD** (merchant country ZA or NG + Visa or Mastercard BIN) | **`za_mpgsvisa_card`** / **`za_mpgsmastercard_card`** / **`ng_mpgsvisa_card`** / **`ng_mpgsmastercard_card`** |
| `budget` | Creditcard.budgetPeriod=0 | None |

### Create Payment - Response parameters

| Rapyd field name | Original PayU field |
| --- | --- |
| `id` | CREDITCARD: `payUReference` (not the Rapyd id) / `secure3D.secure3DId` (= Rapyd payment id) |
| `status` | CREDITCARD: `successful` / `resultCode` (00 when status is CLO for PAYMENT or ACT for RESERVE; P3DS when 3DS is pending; else code from `payu_africa_rapyd_error_code_mappings`) |
| `failure_code` | CREDITCARD: `resultCode` (mapped via `payu_africa_rapyd_error_code_mappings` on connector + status + `failure_code`) |
| `failure_message` | CREDITCARD: `resultMessage` / `displayMessage` (from the same error-code mapping table) |
| `redirect_url` | CREDITCARD: `secure3D.secure3DUrl` (when status ACT and `next_action` 3d_verification) |
| `captured` | CREDITCARD: `TransactionType` (PAYMENT vs RESERVE) |
| `acs_check` | - |
| `last4 / name / expiration_month / expiration_year` | CREDITCARD: `paymentMethodsUsed.cardNumber` (masked = `bin_details.bin_number` + ****** + last4), `paymentMethodsUsed.information` (= `bin_details.brand`), `paymentMethodsUsed.cardExpiry` (echo of request) |
| `original_amount / amount` | CREDITCARD: `paymentMethodsUsed.amountInCents` |
| `merchant_reference_id` | CREDITCARD: `merchantReference` |
| `payment_method_type` | CREDITCARD (`paymentMethodsUsed` method) |
| `gateway reference (internal)` | CREDITCARD: `paymentMethodsUsed.gatewayReference` (read from `rapyd_payments.payment_gateway_token`) |
| `auth_code` | - |

### Accepted values mapping

| Field name | Original PayU value | Rapyd value |
| --- | --- | --- |
| `status` | successful=true, resultCode=00 (PAYMENT) | **CLO** |
| `status` | successful=true, resultCode=00 (RESERVE) | **ACT** |
| `status` | successful=false, resultCode from payu_africa_rapyd_error_code_mappings | **ERR** |
| `status` | successful=true, resultCode=P3DS + secure3D block | ACT + redirect_url (next_action 3d_verification) |

### Capture Payment - Body parameters

| Rapyd field name | Original PayU field |
| --- | --- |
| `payment` | CREDITCARD: `TransactionType`=FINALIZE + `AdditionalInformation.payUReference` |
| `amount` | CREDITCARD: `Basket.amountInCents` (fallback `Creditcard.amountInCents`) on FINALIZE; required, may be below the authorized amount |
| `expected_number_of_captures` | - |

### Accepted values mapping

| Field name | Original PayU value | Rapyd value |
| --- | --- | --- |
| `operation` | CREDITCARD TransactionType=FINALIZE | `POST /v1/payments/{payment}/capture` |

### Capture Payment - Response parameters

| Rapyd field name | Original PayU field |
| --- | --- |
| `status` | CREDITCARD: `successful` / `resultCode` on the FINALIZE response |
| `captured / amount` | CREDITCARD: `paymentMethodsUsed.amountInCents` |
| `failure_code / failure_message` | CREDITCARD: `resultCode` / `resultMessage` |

### Cancel Payment - Body parameters

| Rapyd field name | Original PayU field |
| --- | --- |
| `payment` | CREDITCARD: `TransactionType`=RESERVE_CANCEL + `AdditionalInformation.payUReference` (`Basket` ignored; always full void) |

### Accepted values mapping

| Field name | Original PayU value | Rapyd value |
| --- | --- | --- |
| `operation` | CREDITCARD TransactionType=RESERVE_CANCEL | `DELETE /v1/payments/{payment}` |

### Cancel Payment - Response parameters

| Rapyd field name | Original PayU field |
| --- | --- |
| `status` | CREDITCARD: `successful` / `resultCode` on the RESERVE_CANCEL response |
| `failure_code / failure_message` | CREDITCARD: `resultCode` / `resultMessage` |

### Create Refund - Body parameters

| Rapyd field name | Original PayU field |
| --- | --- |
| `payment` | `TransactionType`=CREDIT + `AdditionalInformation.payUReference` of the original payment |
| `amount` | CREDIT: `Basket.amountInCents` |
| `merchant_reference_id` | CREDIT: `AdditionalInformation.merchantReference` |
| `reason` | - |

### Accepted values mapping

| Field name | Original PayU value | Rapyd value |
| --- | --- | --- |
| `operation` | TransactionType=CREDIT | **POST** /**v1**/**refunds** |

### Create Refund - Response parameters

| Rapyd field name | Original PayU field |
| --- | --- |
| `id` | CREDIT: `payUReference` (of the refund) |
| `status` | CREDIT: `successful` / `resultCode` (Completed or Pending = successful 00; anything else = failure, `pointOfFailure` PAYU) |
| `failure_reason` | CREDIT: `resultMessage` |
| `failure_code` | CREDIT: `resultCode` |
| `amount / currency / payment` | CREDIT: `Basket.amountInCents` / `Basket.currencyCode` |

### Accepted values mapping

| Field name | Original PayU value | Rapyd value |
| --- | --- | --- |
| `status` | successful=true, resultCode 00 | **Completed** or **Pending** |
| `status` | successful=false, PROCESSED_FAILURE code | **Error** / **other** |

### Retrieve Payment - Path parameters

| Rapyd field name | Original PayU field |
| --- | --- |
| `payment` | getTransaction: `AdditionalInformation.payUReference` or `merchantReference` |

### Accepted values mapping

| Field name | Original PayU value | Rapyd value |
| --- | --- | --- |
| `operation` | **getTransaction** | `GET /v1/payments/{payment}` |

### Retrieve Payment - Response parameters

| Rapyd field name | Original PayU field |
| --- | --- |
| `status` | getTransaction: `transactionState` / `successful` / `resultCode` |

### API samples

### Create payment (`POST /v1/payments`)

- - Request

    - ```curl
      curl -X POST 'https://sandboxapi.rapyd.net/v1/payments' \
      -H 'access_key: <your_access_key>' \
      -H 'Content-Type: application/json' \
      -H 'idempotency: <unique_idempotency_key>' \
      -H 'salt: <random_salt>' \
      -H 'signature: <calculated_signature>' \
      -H 'timestamp: <unix_timestamp>' \
      --data '{
          "amount": 150.0,
          "currency": "ZAR",
          "capture": true,
          "merchant_reference_id": "ORDER-2026-000123",
          "description": "2 x Widget + shipping",
          "statement_descriptor": "MYSHOP",
          "complete_payment_url": "https://merchant.example.com/success",
          "error_payment_url": "https://merchant.example.com/error",
          "payment_method": {
              "type": "za_mpgsmastercard_card",
              "fields": {
                  "number": "5123450000000008",
                  "expiration_month": "01",
                  "expiration_year": "39",
                  "cvv": "100",
                  "name": "Test Cardholder"
              }
          },
          "payment_method_options": {
              "3d_required": true
          }
      }'
      ```
- - Response

    - ```json
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "11111111-2222-3333-4444-555555555555"
          },
          "data": {
              "id": "payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
              "amount": 150.0,
              "original_amount": 150.0,
              "currency_code": "ZAR",
              "status": "CLO",
              "captured": true,
              "paid": true,
              "paid_at": 1790000000,
              "payment_method_type": "za_mpgsmastercard_card",
              "payment_method_type_category": "card",
              "payment_method_data": {
                  "type": "za_mpgsmastercard_card",
                  "name": "Test Cardholder",
                  "last4": "0008",
                  "acs_check": "pass",
                  "cvv_check": "unchecked",
                  "bin_details": {
                      "type": null,
                      "brand": null,
                      "country": null,
                      "bin_number": "512345"
                  },
                  "expiration_year": "39",
                  "expiration_month": "01",
                  "fingerprint_token": "ocfp_..."
              },
              "payment_method_options": {
                  "3d_required": true
              },
              "merchant_reference_id": "ORDER-2026-000123",
              "description": "2 x Widget + shipping",
              "statement_descriptor": "MYSHOP",
              "redirect_url": "",
              "complete_payment_url": "https://merchant.example.com/success",
              "error_payment_url": "https://merchant.example.com/error",
              "failure_code": "",
              "failure_message": "",
              "refunded": false,
              "refunded_amount": 0,
              "metadata": {}
          }
      }
      ```

### Create payment - 3DS challenge pending (`POST /v1/payments`, response before 3DS is completed)

- - Request

    - ```json
      //Same as previous request (payment_method_options.3d_required=true)

      curl -X POST 'https://sandboxapi.rapyd.net/v1/payments' \
      -H 'access_key: <your_access_key>' \
      -H 'Content-Type: application/json' \
      -H 'idempotency: <unique_idempotency_key>' \
      -H 'salt: <random_salt>' \
      -H 'signature: <calculated_signature>' \
      -H 'timestamp: <unix_timestamp>' \
      --data '{
          "amount": 150.0,
          "currency": "ZAR",
          "capture": true,
          "merchant_reference_id": "ORDER-2026-000123",
          "description": "2 x Widget + shipping",
          "statement_descriptor": "MYSHOP",
          "complete_payment_url": "https://merchant.example.com/success",
          "error_payment_url": "https://merchant.example.com/error",
          "payment_method": {
              "type": "za_mpgsmastercard_card",
              "fields": {
                  "number": "5123450000000008",
                  "expiration_month": "01",
                  "expiration_year": "39",
                  "cvv": "100",
                  "name": "Test Cardholder"
              }
          },
          "payment_method_options": {
              "3d_required": true
          }
      }'
      ```
- - Response

    - ```json
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "11111111-2222-3333-4444-555555555555"
          },
          "data": {
              "id": "payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
              "amount": 150.0,
              "original_amount": 150.0,
              "currency_code": "ZAR",
              "status": "ACT",
              "captured": false,
              "paid": false,
              "paid_at": 0,
              "payment_method_type": "za_mpgsmastercard_card",
              "payment_method_type_category": "card",
              "payment_method_data": {
                  "type": "za_mpgsmastercard_card",
                  "name": "Test Cardholder",
                  "last4": "0008",
                  "acs_check": "unchecked",
                  "cvv_check": "unchecked",
                  "bin_details": {
                      "type": null,
                      "brand": null,
                      "country": null,
                      "bin_number": "512345"
                  },
                  "expiration_year": "39",
                  "expiration_month": "01",
                  "fingerprint_token": "ocfp_..."
              },
              "payment_method_options": {
                  "3d_required": true
              },
              "merchant_reference_id": "ORDER-2026-000123",
              "description": "2 x Widget + shipping",
              "statement_descriptor": "MYSHOP",
              "redirect_url": "https://sandboxcheckout.rapyd.net/3ds-payment?token=payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
              "complete_payment_url": "https://merchant.example.com/success",
              "error_payment_url": "https://merchant.example.com/error",
              "failure_code": "",
              "failure_message": "",
              "refunded": false,
              "refunded_amount": 0,
              "metadata": {}
          }
      }
      ```

### Create payment - declined by issuer (`POST /v1/payments`)

- - Request

    - ```json
      //Same as previous request.
      curl -X POST 'https://sandboxapi.rapyd.net/v1/payments' \
      -H 'access_key: <your_access_key>' \
      -H 'Content-Type: application/json' \
      -H 'idempotency: <unique_idempotency_key>' \
      -H 'salt: <random_salt>' \
      -H 'signature: <calculated_signature>' \
      -H 'timestamp: <unix_timestamp>' \
      --data '{
          "amount": 150.0,
          "currency": "ZAR",
          "capture": true,
          "merchant_reference_id": "ORDER-2026-000123",
          "description": "2 x Widget + shipping",
          "statement_descriptor": "MYSHOP",
          "complete_payment_url": "https://merchant.example.com/success",
          "error_payment_url": "https://merchant.example.com/error",
          "payment_method": {
              "type": "za_mpgsmastercard_card",
              "fields": {
                  "number": "5123450000000008",
                  "expiration_month": "01",
                  "expiration_year": "39",
                  "cvv": "100",
                  "name": "Test Cardholder"
              }
          },
          "payment_method_options": {
              "3d_required": true
          }
      }'
      ```
- - Response

    - ```json
      {
          "status": {
              "error_code": "ERROR_CREATE_PAYMENT",
              "status": "ERROR",
              "message": "Do not honour",
              "response_code": "",
              "operation_id": "11111111-2222-3333-4444-555555555555"
          },
          "data": {
              "id": "payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
              "amount": 150.0,
              "original_amount": 150.0,
              "currency_code": "ZAR",
              "status": "ERR",
              "captured": false,
              "paid": false,
              "paid_at": 0,
              "payment_method_type": "za_mpgsmastercard_card",
              "payment_method_type_category": "card",
              "payment_method_data": {
                  "type": "za_mpgsmastercard_card",
                  "name": "Test Cardholder",
                  "last4": "0008",
                  "acs_check": "pass",
                  "cvv_check": "unchecked",
                  "bin_details": {
                      "type": null,
                      "brand": null,
                      "country": null,
                      "bin_number": "512345"
                  },
                  "expiration_year": "39",
                  "expiration_month": "01",
                  "fingerprint_token": "ocfp_..."
              },
              "payment_method_options": {
                  "3d_required": true
              },
              "merchant_reference_id": "ORDER-2026-000123",
              "description": "2 x Widget + shipping",
              "statement_descriptor": "MYSHOP",
              "redirect_url": "",
              "complete_payment_url": "https://merchant.example.com/success",
              "error_payment_url": "https://merchant.example.com/error",
              "failure_code": "05",
              "failure_message": "Do not honour",
              "refunded": false,
              "refunded_amount": 0,
              "metadata": {}
          }
      }
      ```

### Create payment - Account Funding Transaction (`POST /v1/payments`)

- - Request

    - ```curl
      curl -X POST 'https://sandboxapi.rapyd.net/v1/payments' \
      -H 'access_key: <your_access_key>' \
      -H 'Content-Type: application/json' \
      -H 'idempotency: <unique_idempotency_key>' \
      -H 'salt: <random_salt>' \
      -H 'signature: <calculated_signature>' \
      -H 'timestamp: <unix_timestamp>' \
      --data '{
          "amount": 150.0,
          "currency": "ZAR",
          "capture": true,
          "payment_method": {
              "type": "za_mpgsvisa_card",
              "fields": {
                  "number": "4508750015741019",
                  "expiration_month": "01",
                  "expiration_year": "39",
                  "cvv": "100",
                  "name": "Test Cardholder"
              }
          },
          "payment_method_options": {
              "aft": true,
              "purpose_code": "family_support",
              "3d_required": true
          },
          "ewallet": "ewallet_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
          "customer": "cus_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
          "address": {
              "name": "Test Cardholder",
              "line_1": "1 Long Street",
              "city": "Cape Town",
              "country": "ZA"
          },
          "complete_payment_url": "https://merchant.example.com/success",
          "error_payment_url": "https://merchant.example.com/error"
      }'
      ```
- - Response

    - ```json
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "11111111-2222-3333-4444-555555555555"
          },
          "data": {
              "id": "payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
              "amount": 150.0,
              "original_amount": 150.0,
              "currency_code": "ZAR",
              "status": "CLO",
              "captured": true,
              "paid": true,
              "paid_at": 1790000000,
              "payment_method_type": "za_mpgsvisa_card",
              "payment_method_type_category": "card",
              "payment_method_data": {
                  "type": "za_mpgsvisa_card",
                  "name": "Test Cardholder",
                  "last4": "1019",
                  "acs_check": "pass",
                  "cvv_check": "unchecked",
                  "bin_details": {
                      "type": null,
                      "brand": null,
                      "country": null,
                      "bin_number": "450875"
                  },
                  "expiration_year": "39",
                  "expiration_month": "01",
                  "fingerprint_token": "ocfp_..."
              },
              "payment_method_options": {
                  "aft": true,
                  "purpose_code": "family_support",
                  "3d_required": true
              },
              "merchant_reference_id": "",
              "description": "",
              "statement_descriptor": "",
              "redirect_url": "",
              "complete_payment_url": "https://merchant.example.com/success",
              "error_payment_url": "https://merchant.example.com/error",
              "failure_code": "",
              "failure_message": "",
              "refunded": false,
              "refunded_amount": 0,
              "metadata": {},
              "ewallet_id": "ewallet_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"
          }
      }
      ```

### Create payment - AFT rejected by connector pre-flight (`POST /v1/payments`)

- - Request

    - ```json
      //Same as previous AFT request, merchant MCC not eligible.
      {
          "amount": 150.0,
          "currency": "ZAR",
          "capture": true,
          "payment_method": {
              "type": "za_mpgsvisa_card",
              "fields": {
                  "number": "4508750015741019",
                  "expiration_month": "01",
                  "expiration_year": "39",
                  "cvv": "100",
                  "name": "Test Cardholder"
              }
          },
          "payment_method_options": {
              "aft": true,
              "purpose_code": "family_support",
              "3d_required": true
          },
          "ewallet": "ewallet_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
          "customer": "cus_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
          "address": {
              "name": "Test Cardholder",
              "line_1": "1 Long Street",
              "city": "Cape Town",
              "country": "ZA"
          },
          "complete_payment_url": "https://merchant.example.com/success",
          "error_payment_url": "https://merchant.example.com/error"
      }
      '
      ```
- - Response

    - ```json
      {
          "status": {
              "error_code": "ERROR_CREATE_PAYMENT",
              "status": "ERROR",
              "message": "AFT pre-flight: MCC 5999 is not supported by Rapyd for account funding transactions (supported MCCs: 4829, 6012, 6051, 6211, 6540).",
              "response_code": "",
              "operation_id": "11111111-2222-3333-4444-555555555555"
          },
          "data": {
              "id": "payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
              "amount": 150.0,
              "original_amount": 150.0,
              "currency_code": "ZAR",
              "status": "ERR",
              "captured": false,
              "paid": false,
              "paid_at": 0,
              "payment_method_type": "za_mpgsvisa_card",
              "payment_method_type_category": "card",
              "payment_method_data": {
                  "type": "za_mpgsvisa_card",
                  "name": "Test Cardholder",
                  "last4": "1019",
                  "acs_check": "fail",
                  "cvv_check": "unchecked",
                  "bin_details": {
                      "type": null,
                      "brand": null,
                      "country": null,
                      "bin_number": "450875"
                  },
                  "expiration_year": "39",
                  "expiration_month": "01",
                  "fingerprint_token": "ocfp_..."
              },
              "payment_method_options": {
                  "aft": true,
                  "purpose_code": "family_support",
                  "3d_required": true
              },
              "merchant_reference_id": "",
              "description": "",
              "statement_descriptor": "",
              "redirect_url": "",
              "complete_payment_url": "https://merchant.example.com/success",
              "error_payment_url": "https://merchant.example.com/error",
              "failure_code": "AFT_VALIDATION_FAILED",
              "failure_message": "AFT pre-flight: MCC 5999 is not supported by Rapyd for account funding transactions (supported MCCs: 4829, 6012, 6051, 6211, 6540).",
              "refunded": false,
              "refunded_amount": 0,
              "metadata": {},
              "ewallet_id": "ewallet_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"
          }
      }
      ```

### Create payment - authorize only (`POST /v1/payments`, capture=false)

- - Request

    - ```curl
      curl -X POST 'https://sandboxapi.rapyd.net/v1/payments' \
      -H 'access_key: <your_access_key>' \
      -H 'Content-Type: application/json' \
      -H 'idempotency: <unique_idempotency_key>' \
      -H 'salt: <random_salt>' \
      -H 'signature: <calculated_signature>' \
      -H 'timestamp: <unix_timestamp>' \
      --data '{
          "amount": 150.0,
          "currency": "ZAR",
          "capture": false,
          "merchant_reference_id": "ORDER-2026-000123",
          "description": "2 x Widget + shipping",
          "statement_descriptor": "MYSHOP",
          "complete_payment_url": "https://merchant.example.com/success",
          "error_payment_url": "https://merchant.example.com/error",
          "payment_method": {
              "type": "za_mpgsmastercard_card",
              "fields": {
                  "number": "5123450000000008",
                  "expiration_month": "01",
                  "expiration_year": "39",
                  "cvv": "100",
                  "name": "Test Cardholder"
              }
          },
          "payment_method_options": {
              "3d_required": true
          }
      }'
      ```
- - Response

    - ```json
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "11111111-2222-3333-4444-555555555555"
          },
          "data": {
              "id": "payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
              "amount": 150.0,
              "original_amount": 150.0,
              "currency_code": "ZAR",
              "status": "ACT",
              "captured": false,
              "paid": false,
              "paid_at": 0,
              "payment_method_type": "za_mpgsmastercard_card",
              "payment_method_type_category": "card",
              "payment_method_data": {
                  "type": "za_mpgsmastercard_card",
                  "name": "Test Cardholder",
                  "last4": "0008",
                  "acs_check": "pass",
                  "cvv_check": "unchecked",
                  "bin_details": {
                      "type": null,
                      "brand": null,
                      "country": null,
                      "bin_number": "512345"
                  },
                  "expiration_year": "39",
                  "expiration_month": "01",
                  "fingerprint_token": "ocfp_..."
              },
              "payment_method_options": {
                  "3d_required": true
              },
              "merchant_reference_id": "ORDER-2026-000123",
              "description": "2 x Widget + shipping",
              "statement_descriptor": "MYSHOP",
              "redirect_url": "",
              "complete_payment_url": "https://merchant.example.com/success",
              "error_payment_url": "https://merchant.example.com/error",
              "failure_code": "",
              "failure_message": "",
              "refunded": false,
              "refunded_amount": 0,
              "metadata": {}
          }
      }
      ```

### Capture payment (`POST /v1/payments/{payment}/capture`)

- - Request

    - ```curl
      curl -X POST 'https://sandboxapi.rapyd.net/v1/payments/payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d/capture' \
      -H 'access_key: <your_access_key>' \
      -H 'Content-Type: application/json' \
      -H 'idempotency: <unique_idempotency_key>' \
      -H 'salt: <random_salt>' \
      -H 'signature: <calculated_signature>' \
      -H 'timestamp: <unix_timestamp>' \
      --data '{
          "amount": 100.0
      }'
      ```
- - Response

    - ```json
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "11111111-2222-3333-4444-555555555555"
          },
          "data": {
              "id": "payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
              "amount": 100.0,
              "original_amount": 150.0,
              "currency_code": "ZAR",
              "status": "CLO",
              "captured": true,
              "paid": true,
              "paid_at": 1790000100,
              "payment_method_type": "za_mpgsmastercard_card",
              "payment_method_type_category": "card",
              "payment_method_data": {
                  "type": "za_mpgsmastercard_card",
                  "name": "Test Cardholder",
                  "last4": "0008",
                  "acs_check": "pass",
                  "cvv_check": "unchecked",
                  "bin_details": {
                      "type": null,
                      "brand": null,
                      "country": null,
                      "bin_number": "512345"
                  },
                  "expiration_year": "39",
                  "expiration_month": "01",
                  "fingerprint_token": "ocfp_..."
              },
              "payment_method_options": {
                  "3d_required": true
              },
              "merchant_reference_id": "ORDER-2026-000123",
              "description": "2 x Widget + shipping",
              "statement_descriptor": "MYSHOP",
              "redirect_url": "",
              "complete_payment_url": "https://merchant.example.com/success",
              "error_payment_url": "https://merchant.example.com/error",
              "failure_code": "",
              "failure_message": "",
              "refunded": false,
              "refunded_amount": 0,
              "metadata": {}
          }
      }
      ```

### Cancel payment (`DELETE /v1/payments/{payment}`)

- - Request

    - ```curl
      curl -X DELETE 'https://sandboxapi.rapyd.net/v1/payments/payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d' \
      -H 'access_key: <your_access_key>' \
      -H 'Content-Type: application/json' \
      -H 'salt: <random_salt>' \
      -H 'signature: <calculated_signature>' \
      -H 'timestamp: <unix_timestamp>'
      ```
- - Response

    - ```json
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "11111111-2222-3333-4444-555555555555"
          },
          "data": {
              "id": "payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
              "amount": 150.0,
              "original_amount": 150.0,
              "currency_code": "ZAR",
              "status": "CAN",
              "captured": false,
              "paid": false,
              "paid_at": 0,
              "payment_method_type": "za_mpgsmastercard_card",
              "payment_method_type_category": "card",
              "payment_method_data": {
                  "type": "za_mpgsmastercard_card",
                  "name": "Test Cardholder",
                  "last4": "0008",
                  "acs_check": "pass",
                  "cvv_check": "unchecked",
                  "bin_details": {
                      "type": null,
                      "brand": null,
                      "country": null,
                      "bin_number": "512345"
                  },
                  "expiration_year": "39",
                  "expiration_month": "01",
                  "fingerprint_token": "ocfp_..."
              },
              "payment_method_options": {
                  "3d_required": true
              },
              "merchant_reference_id": "ORDER-2026-000123",
              "description": "2 x Widget + shipping",
              "statement_descriptor": "MYSHOP",
              "redirect_url": "",
              "complete_payment_url": "https://merchant.example.com/success",
              "error_payment_url": "https://merchant.example.com/error",
              "failure_code": "",
              "failure_message": "",
              "refunded": false,
              "refunded_amount": 0,
              "metadata": {}
          }
      }
      ```

### Create refund (`POST /v1/refunds`)

- - Request

    - ```curl
      curl -X POST 'https://sandboxapi.rapyd.net/v1/refunds' \
      -H 'access_key: <your_access_key>' \
      -H 'Content-Type: application/json' \
      -H 'idempotency: <unique_idempotency_key>' \
      -H 'salt: <random_salt>' \
      -H 'signature: <calculated_signature>' \
      -H 'timestamp: <unix_timestamp>' \
      --data '{
          "payment": "payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
          "amount": 100.0,
          "merchant_reference_id": "REFUND-000123",
          "reason": "Customer request"
      }'
      ```
- - Response

    - ```json
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "11111111-2222-3333-4444-555555555555"
          },
          "data": {
              "id": "refund_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
              "amount": 100.0,
              "payment": "payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
              "currency": "ZAR",
              "status": "Completed",
              "failure_reason": "",
              "merchant_reference_id": "REFUND-000123",
              "reason": "Customer request",
              "created_at": 1790000200,
              "payment_method_type": "za_mpgsmastercard_card",
              "metadata": {}
          }
      }
      ```

### Create refund - Visa AFT payment rejected (`POST /v1/refunds`)

- - Request

    - ```json
      //Same as previous request for a Visa AFT payment.
      curl -X POST 'https://sandboxapi.rapyd.net/v1/refunds' \
      -H 'access_key: <your_access_key>' \
      -H 'Content-Type: application/json' \
      -H 'idempotency: <unique_idempotency_key>' \
      -H 'salt: <random_salt>' \
      -H 'signature: <calculated_signature>' \
      -H 'timestamp: <unix_timestamp>' \
      --data '{
          "payment": "payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
          "amount": 100.0,
          "merchant_reference_id": "REFUND-000123",
          "reason": "Customer request"
      }
      '
      ```
- - Response

    - ```json
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "11111111-2222-3333-4444-555555555555"
          },
          "data": {
              "id": "refund_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
              "amount": 100.0,
              "payment": "payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
              "currency": "ZAR",
              "status": "Error",
              "failure_reason": "Visa does not allow refunds on Account Funding Transactions; the payment can only be reversed by a void before settlement. Contact Rapyd Support.",
              "merchant_reference_id": "REFUND-000123",
              "reason": "Customer request",
              "created_at": 1790000200,
              "payment_method_type": "za_mpgsvisa_card",
              "metadata": {}
          }
      }
      ```

### Retrieve payment (`GET /v1/payments/{payment}`)

- - Request

    - ```curl
      curl -X GET 'https://sandboxapi.rapyd.net/v1/payments/payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d' \
      -H 'access_key: <your_access_key>' \
      -H 'Content-Type: application/json' \
      -H 'salt: <random_salt>' \
      -H 'signature: <calculated_signature>' \
      -H 'timestamp: <unix_timestamp>'
      ```
- - Response

    - ```json
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "11111111-2222-3333-4444-555555555555"
          },
          "data": {
              "id": "payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
              "amount": 150.0,
              "original_amount": 150.0,
              "currency_code": "ZAR",
              "status": "CLO",
              "captured": true,
              "paid": true,
              "paid_at": 1790000000,
              "payment_method_type": "za_mpgsmastercard_card",
              "payment_method_type_category": "card",
              "payment_method_data": {
                  "type": "za_mpgsmastercard_card",
                  "name": "Test Cardholder",
                  "last4": "0008",
                  "acs_check": "pass",
                  "cvv_check": "unchecked",
                  "bin_details": {
                      "type": null,
                      "brand": null,
                      "country": null,
                      "bin_number": "512345"
                  },
                  "expiration_year": "39",
                  "expiration_month": "01",
                  "fingerprint_token": "ocfp_..."
              },
              "payment_method_options": {
                  "3d_required": true
              },
              "merchant_reference_id": "ORDER-2026-000123",
              "description": "2 x Widget + shipping",
              "statement_descriptor": "MYSHOP",
              "redirect_url": "",
              "complete_payment_url": "https://merchant.example.com/success",
              "error_payment_url": "https://merchant.example.com/error",
              "failure_code": "",
              "failure_message": "",
              "refunded": false,
              "refunded_amount": 0,
              "metadata": {}
          }
      }
      ```
