Skip to main content

Documentation

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. No connector-specific headers.

  • Supported workflows

    • 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 -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

      • {
    "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

      • //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

      • {
    "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

      • //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

      • {
    "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 -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

      • {
    "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

      • //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

      • {
    "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 -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

      • {
    "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 -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

      • {
    "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 -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

      • {
    "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 -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

      • {
    "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

      • //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

      • {
    "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 -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

      • {
    "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": {}
    }
}
In this section: