Skip to main content

Documentation

MPGS Card - NG Connector
Connector overview

  • Connector name: MPGS Card - NG

  • Payment method type: ng_mpgsvisa_card (Visa in Nigeria - Visa card payments in NGN processed through MPGS (category card, flow card).); ng_mpgsmastercard_card (Mastercard in Nigeria - Mastercard card payments in NGN processed through MPGS (category card, flow card).)

  • Gateway name: MPGS (Mastercard Payment Gateway Services) - Rapyd gateway mpgs_ng

  • Supported countries and currencies: Nigeria (NG), NGN

  • Gateway: Mastercard Payment Gateway Services (MPGS) REST API v100, direct server-to-server card API (PUT .../merchant/{merchantId}/order/{orderId}/transaction/{transactionId}). 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) to MPGS.

Note

Card payments are processed as standard e-commerce payments, including when initiation_type is moto. Rapyd performs the 3DS authentication, and 3DS data cannot be supplied by the merchant. Merchant-initiated payments are currently limited: the original_payment reference is not used by the connector at present.

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/recurring/installment/unscheduled maps to MPGS CIT/MIT agreement fields. Acquirer response code and message are returned as failure_code / failure_message on declines.

NGN 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 per authorization.

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.

Refund status is not updated after creation.

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: a customer-initiated first payment can store the card agreement (save_payment_method).

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.

15000.00

Merchant

currency

-

string

Required

-

NGN

-

ISO 4217 currency code.

NGN

Merchant

payment_method

-

object

Required

-

-

-

Card payment method object.

{...}

Merchant

type

payment_method

string

Required

-

ng_mpgsvisa_card, ng_mpgsmastercard_card

-

Payment method type.

ng_mpgsvisa_card

Merchant

number

payment_method.fields

string

Required

-

-

-

Card number (PAN).

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

Required

-

-

-

Cardholder name.

Test Cardholder

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

-

string

Optional

-

customer_present, installment, 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

-

-

-

Reference to the payment that first stored the card. Not used by the connector at present.

payment_0f0e0d0c0b0a09080706050403020100

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

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_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d

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.

15000.00

Rapyd

merchant_reference_id

-

string

-

Echo of the merchant reference.

ORDER-2026-000123

Carried over

payment_method_type

-

string

ng_mpgsvisa_card, ng_mpgsmastercard_card

Payment method type used.

ng_mpgsvisa_card

Carried over

gateway reference (internal)

-

string

-

MPGS order id stored as the payment gateway token.

payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d

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_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d

Merchant

amount

-

number

Optional

Full authorized amount

-

Greater than 0 and not more than the remaining authorized amount

Amount to capture.

10000.00

Merchant

expected_number_of_captures

payment_method_options

integer

Optional

1

-

Integer >= 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.

10000.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_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d

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_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d

Merchant

amount

-

number

Optional

Full captured amount

-

-

Refund amount; partial allowed.

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

amount / currency / payment

-

number / string

-

Refund amount, currency and payment ID.

10000.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_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d

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 payment method type 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

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

-

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)

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)

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": 15000.0,
    "currency": "NGN",
    "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": "ng_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": 15000.0,
        "original_amount": 15000.0,
        "currency_code": "NGN",
        "status": "CLO",
        "captured": true,
        "paid": true,
        "paid_at": 1790000000,
        "payment_method_type": "ng_mpgsmastercard_card",
        "payment_method_type_category": "card",
        "payment_method_data": {
            "type": "ng_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 request as above (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": 15000.0,
    "currency": "NGN",
    "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": "ng_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": 15000.0,
        "original_amount": 15000.0,
        "currency_code": "NGN",
        "status": "ACT",
        "captured": false,
        "paid": false,
        "paid_at": 0,
        "payment_method_type": "ng_mpgsmastercard_card",
        "payment_method_type_category": "card",
        "payment_method_data": {
            "type": "ng_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

      • 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": 15000.0,
    "currency": "NGN",
    "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": "ng_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": 15000.0,
        "original_amount": 15000.0,
        "currency_code": "NGN",
        "status": "ERR",
        "captured": false,
        "paid": false,
        "paid_at": 0,
        "payment_method_type": "ng_mpgsmastercard_card",
        "payment_method_type_category": "card",
        "payment_method_data": {
            "type": "ng_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 - 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": 15000.0,
    "currency": "NGN",
    "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": "ng_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": 15000.0,
        "original_amount": 15000.0,
        "currency_code": "NGN",
        "status": "ACT",
        "captured": false,
        "paid": false,
        "paid_at": 0,
        "payment_method_type": "ng_mpgsmastercard_card",
        "payment_method_type_category": "card",
        "payment_method_data": {
            "type": "ng_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": 10000.0
}'

    • Response

      • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "11111111-2222-3333-4444-555555555555"
    },
    "data": {
        "id": "payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
        "amount": 10000.0,
        "original_amount": 15000.0,
        "currency_code": "NGN",
        "status": "CLO",
        "captured": true,
        "paid": true,
        "paid_at": 1790000100,
        "payment_method_type": "ng_mpgsmastercard_card",
        "payment_method_type_category": "card",
        "payment_method_data": {
            "type": "ng_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": 15000.0,
        "original_amount": 15000.0,
        "currency_code": "NGN",
        "status": "CAN",
        "captured": false,
        "paid": false,
        "paid_at": 0,
        "payment_method_type": "ng_mpgsmastercard_card",
        "payment_method_type_category": "card",
        "payment_method_data": {
            "type": "ng_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": 10000.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": 10000.0,
        "payment": "payment_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
        "currency": "NGN",
        "status": "Completed",
        "failure_reason": "",
        "merchant_reference_id": "REFUND-000123",
        "reason": "Customer request",
        "created_at": 1790000200,
        "payment_method_type": "ng_mpgsmastercard_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": 15000.0,
        "original_amount": 15000.0,
        "currency_code": "NGN",
        "status": "CLO",
        "captured": true,
        "paid": true,
        "paid_at": 1790000000,
        "payment_method_type": "ng_mpgsmastercard_card",
        "payment_method_type_category": "card",
        "payment_method_data": {
            "type": "ng_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: