Skip to main content

Documentación

Scan to Pay Connector
Connector overview

  • Connector name: Scan to Pay

  • Payment method type: za_scan_to_pay_ewallet (Scan to Pay (Oltio / Masterpass QR). Category ewallet. The shopper scans a QR code with a Scan to Pay-enabled banking or wallet app and approves the payment in the app. Refundable, not cancelable, expirable (max 1800 seconds).)

  • Gateway name: Scan to Pay (gateway type scan_to_pay; Oltio Bluebox / Masterpass API)

  • Supported countries and currencies: South Africa (ZA), ZAR

  • Payment is asynchronous. Create payment returns status ACT with a QR code in visual_codes. The final result arrives from the gateway by encrypted webhook.

Capabilities

API request

Endpoint

Unique capabilities

Limitations

Create payment

POST /v1/payments

Returns a QR code image (base64 PNG) in visual_codes under "Scan to Pay QR". Optional mobile deep link in redirect_url, based on payment_method.fields.preferred_app. QR code is single use and expires after 30 minutes.

No partial payments, tips or reusable QR codes; payments cannot be canceled.

Create refund

POST /v1/refunds

Refund is asynchronous: status Pending on creation, then Completed or Rejected from the gateway refund webhook.

Completed payments only; refunds cannot be canceled.

Retrieve payment

GET /v1/payments/{payment}

Returns the payment as stored by Rapyd, including the QR code and current status.

Returns stored Rapyd data, with no live gateway lookup.

  • Header parameters: Standard Rapyd headers. No connector-specific headers.

  • Supported workflows

    • eWallet payments: the shopper pays by scanning the QR code returned in visual_codes.

    • Unique workflow - QR code payment: display visual_codes["Scan to Pay QR"] to the shopper. The shopper scans it with a Scan to Pay-enabled app (Samsung Pay, Nedbank, Capitec, FNB, RMB, Absa, Standard Bank or Scan to Pay) and approves. Rapyd moves the payment to CLO and sends PAYMENT_COMPLETED.

    • Unique workflow - mobile deep link: when the shopper is on a mobile device and preferred_app has a deep link configured, redirect_url opens that app directly. After payment the app returns the shopper to the Rapyd checkout thank-you page.

    • Refund workflow: create the refund, receive status Pending, then wait for the REFUND_COMPLETED or rejection webhook.

Field mapping tables
Create Payment - Body parameters

Nota

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

-

-

Major units (ZAR). Sent to the gateway as-is as the QR amount.

Amount to charge.

300

Merchant

currency

-

string

Required

-

ZAR

Only ZAR is configured for this payment method type.

Three-letter ISO 4217 currency code.

ZAR

Merchant

payment_method

-

object

Required

-

-

-

Payment method object.

-

Merchant

type

payment_method

string

Required

-

za_scan_to_pay_ewallet

-

Payment method type.

za_scan_to_pay_ewallet

Merchant

fields

payment_method

object

Required

-

-

-

Payment method fields.

-

Merchant

preferred_app

payment_method.fields

string

Required

-

Samsung Pay, Nedbank, Capitec, FNB, RMB, Absa, Standard Bank, Scan to Pay

Must match regex ^(Samsung Pay|Nedbank|Capitec|FNB|RMB|Absa|Standard Bank|Scan to Pay)$.

Banking or wallet app the shopper wants to use. On a mobile device the connector builds a deep link that opens this app.

Capitec

Merchant

description

-

string

Optional

-

-

-

Payment description. Sent to the gateway as the QR short description.

Order 12345

Merchant

complete_payment_url

-

string

Optional

-

-

Valid URL.

URL the shopper is sent to after a successful payment (Rapyd hosted pages).

https://merchant.example.com/success

Merchant

error_payment_url

-

string

Optional

-

-

Valid URL.

URL the shopper is sent to after a failed payment.

https://merchant.example.com/error

Merchant

merchant_reference_id

-

string

Optional

-

-

-

Merchant's own reference for the payment.

order_12345

Merchant

customer

-

object

Optional

-

-

-

Customer details (inline) or customer ID.

-

Merchant

email

customer

string

Optional

-

-

-

Customer email.

shopper@example.com

Merchant

name

customer

string

Optional

-

-

-

Customer name.

Jane Doe

Merchant

phone_number

customer

string

Optional

-

-

E.164 format.

Customer phone number.

+27821234567

Merchant

metadata

-

object

Optional

-

-

-

Merchant-defined JSON object.

{"order": "12345"}

Merchant

expiration

-

number

Optional

1800 seconds after creation

-

Maximum 1800 seconds (payment_method_type_maximum_expiration_seconds = 1800). The gateway expires the QR code after 30 minutes.

Payment expiration (Unix time).

1782389078

Merchant

capture

-

boolean

Optional

-

Must be omitted

Rapyd rejects the key for non-card methods (ERROR_CREATE_PAYMENT_CAPTURE_FOR_CARD_METHODS_ONLY).

Do not send for this method.

-

Merchant

Create Payment - Response parameters

Nota

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

data

string

-

Rapyd payment ID.

payment_dd5c6fad1382b0622ec453207b0a7c31

Rapyd

status

data

string

ACT, CLO, ERR, EXP

Payment status. ACT after the QR code is created. CLO after an approved gateway webhook. ERR after a failed webhook or a failed create.

ACT

Rapyd

amount

data

number

-

Amount paid. 0 while ACT; set from the gateway webhook amount when approved.

0

Rapyd / Gateway

original_amount

data

number

-

Requested amount.

300

Rapyd

currency_code

data

string

ZAR

Currency.

ZAR

Rapyd

visual_codes

data

object

-

QR code image. Key "Scan to Pay QR", value is a base64 PNG data URI (700 px, error level M) generated by the connector from the gateway code.

{"Scan to Pay QR": "data:image/png;base64,..."}

Gateway (generated by connector)

textual_codes

data

object

-

Not populated by this connector.

{}

Rapyd

redirect_url

data

string

-

Deep link that opens the selected preferred_app with the payment reference and a return URL. Set only when the shopper is on a mobile device, the app is configured, and the deep-link feature flag is on. Empty otherwise.

-

Rapyd (built by connector)

instructions

data

array

-

Shopper instructions from the payment method type configuration (3 steps: scan QR with your Scan to Pay app; on mobile select your app; complete payment).

-

Rapyd

expiration

data

number

-

Payment expiration (Unix time). Max 1800 seconds.

1782389078

Rapyd

next_action

data

string

pending_confirmation

Shopper action is pending (scan / pay in app).

pending_confirmation

Rapyd

payment_method_type

data

string

za_scan_to_pay_ewallet

Payment method type.

za_scan_to_pay_ewallet

Rapyd

payment_method_type_category

data

string

ewallet

Category.

ewallet

Rapyd

paid

data

boolean

-

true after the approved webhook completes the payment.

false

Rapyd

failure_code

data

string

-

Set on failure. The connector uses ERROR_COMPLETE_PAYMENT for failed webhooks.

-

Rapyd

complete_payment_url / error_payment_url

data

string

-

Echo of the merchant URLs.

https://merchant.example.com/success

Merchant

Create Refund - Body parameters

Nota

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

-

-

Payment must be CLO (paid).

ID of the payment to refund.

payment_dd5c6fad1382b0622ec453207b0a7c31

Merchant

amount

-

number

Optional

Full payment amount

-

Major units. Cannot exceed the refundable balance.

Amount to refund. Sent to the gateway as amount.

100

Merchant

currency

-

string

Optional

Payment currency

ZAR

Must match the payment currency.

Refund currency.

ZAR

Merchant

merchant_reference_id

-

string

Optional

-

-

-

Merchant's own refund reference.

refund_order_12345

Merchant

reason

-

string

Optional

-

-

-

Refund reason.

Customer request

Merchant

metadata

-

object

Optional

-

-

-

Merchant-defined JSON object.

{}

Merchant

Create Refund - Response parameters

Nota

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

data

string

-

Rapyd refund ID.

refund_0a1b2c3d4e5f60718293a4b5c6d7e8f9

Rapyd

status

data

string

Pending, Completed, Rejected, Error

Refund status. Pending after the gateway accepts the refund request (gateway returns no final status). Completed or Rejected after the encrypted refund webhook. Error if the gateway call fails or the response is invalid.

Pending

Rapyd

amount

data

number

-

Refund amount.

100

Rapyd

payment

data

string

-

Refunded payment ID.

payment_dd5c6fad1382b0622ec453207b0a7c31

Rapyd

currency

data

string

ZAR

Currency.

ZAR

Rapyd

merchant_reference_id

data

string

-

Echo of merchant reference.

refund_order_12345

Merchant

failure_reason

data

string

-

Failure reason when rejected or error.

-

Rapyd

Retrieve Payment - Path parameters

Nota

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_dd5c6fad1382b0622ec453207b0a7c31

Merchant

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.

Migration notes

  • PayU Africa equivalent payment method: MASTERPASS.

Field mapping (Rapyd field to original PayU field)
Create Payment - Body parameters

Rapyd field name

Original PayU field

amount

Basket.amountInCents

currency

Basket.currencyCode

payment_method

AdditionalInformation.supportedPaymentMethods

type

AdditionalInformation.supportedPaymentMethods = MASTERPASS

fields

None (new in Rapyd)

preferred_app

None (new in Rapyd)

description

Basket.description

complete_payment_url

AdditionalInformation.returnUrl

error_payment_url

AdditionalInformation.cancelUrl

merchant_reference_id

merchantReference

customer

Customer

email

Customer.email

name

Customer.firstName + Customer.lastName

phone_number

Customer.mobile (with Customer.countryCode)

metadata

None (new in Rapyd)

expiration

-

capture

None

Accepted values mapping

Field name

Original PayU value

Rapyd value

payment_method.type

MASTERPASS

za_scan_to_pay_ewallet

amount

amountInCents (e.g. 30000)

amount in major units (e.g. 300)

Create Payment - Response parameters

Rapyd field name

Original PayU field

id

payUReference

status

resultCode / successful

amount

Basket.amountInCents

original_amount

Basket.amountInCents

currency_code

Basket.currencyCode

visual_codes

paymentMethodsUsed[masterPass].qrCode

textual_codes

None

redirect_url

None

instructions

None

expiration

None

next_action

None

payment_method_type

AdditionalInformation.supportedPaymentMethods

payment_method_type_category

None

paid

successful

failure_code

resultCode

complete_payment_url / error_payment_url

AdditionalInformation.returnUrl / cancelUrl

Accepted values mapping

Field name

Original PayU value

Rapyd value

status

successful=true, resultCode 00

ACT or CLO

status

successful=false, resultCode 05 (ACQUIRER)

ERR

status

successful=false, resultCode P015

CAN

status

successful=false, resultCode 994

EXP

Create Refund - Body parameters

Rapyd field name

Original PayU field

payment

payUReference (original transaction)

amount

Credit amount / Basket.amountInCents

currency

Basket.currencyCode

merchant_reference_id

merchantReference

reason

-

metadata

None (new in Rapyd)

Accepted values mapping

Field name

Original PayU value

Rapyd value

amount

amountInCents

amount in major units

Create Refund - Response parameters

Rapyd field name

Original PayU field

id

-

status

resultCode / successful

amount

Credit amount

payment

payUReference

currency

Basket.currencyCode

merchant_reference_id

merchantReference

failure_reason

resultMessage

Accepted values mapping

Field name

Original PayU value

Rapyd value

status (gateway webhook)

N/A

Completed

status (gateway webhook)

N/A

Rejected

Retrieve Payment - Path parameters

Rapyd field name

Original PayU field

payment

payUReference (getTransaction)

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": 300,
  "currency": "ZAR",
  "description": "Order 12345",
  "payment_method": {
    "type": "za_scan_to_pay_ewallet",
    "fields": {
      "preferred_app": "Capitec"
    }
  },
  "customer": {
    "email": "shopper@example.com",
    "name": "Jane Doe",
    "phone_number": "+27821234567"
  },
  "complete_payment_url": "https://merchant.example.com/success",
  "error_payment_url": "https://merchant.example.com/error",
  "merchant_reference_id": "order_12345"
}'

    • Response

      • {
  "status": {
    "error_code": "",
    "status": "SUCCESS",
    "message": "",
    "response_code": "",
    "operation_id": "786cb9c5-a8fd-4560-a2a2-234340b0afeb"
  },
  "data": {
    "id": "payment_dd5c6fad1382b0622ec453207b0a7c31",
    "amount": 0,
    "original_amount": 300,
    "is_partial": false,
    "currency_code": "ZAR",
    "country_code": "ZA",
    "status": "ACT",
    "description": "Order 12345",
    "merchant_reference_id": "order_12345",
    "customer_token": "cus_4d29a021beb3ba2a081ac1e84b5dd12f",
    "payment_method": "other_30498d78d580cea56ec98748b492cde5",
    "payment_method_data": {
      "id": "other_30498d78d580cea56ec98748b492cde5",
      "type": "za_scan_to_pay_ewallet",
      "category": "ewallet",
      "metadata": {},
      "next_action": "not_applicable"
    },
    "auth_code": null,
    "expiration": 1782389078,
    "captured": true,
    "refunded": false,
    "refunded_amount": 0,
    "redirect_url": "",
    "complete_payment_url": "https://merchant.example.com/success",
    "error_payment_url": "https://merchant.example.com/error",
    "created_at": 1781179477,
    "metadata": {},
    "failure_code": "",
    "failure_message": "",
    "paid": false,
    "paid_at": 0,
    "visual_codes": {
      "Scan to Pay QR": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    },
    "textual_codes": {},
    "instructions": [
      {
        "name": "instructions",
        "steps": [
          {
            "step1": "On your mobile device, scan the QR code displayed on the checkout page using your preferred Scan to Pay app"
          },
          {
            "step2": "On mobile, select your preferred payment app from the dropdown to open the app"
          },
          {
            "step3": "Complete the payment in your selected payment app"
          }
        ]
      }
    ],
    "ewallet_id": "ewallet_ba37d302e173e089078bf8cbadf68cc8",
    "payment_method_type": "za_scan_to_pay_ewallet",
    "payment_method_type_category": "ewallet",
    "initiation_type": "customer_present",
    "next_action": "pending_confirmation",
    "error_code": ""
  }
}
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_dd5c6fad1382b0622ec453207b0a7c31",
  "amount": 100,
  "currency": "ZAR",
  "merchant_reference_id": "refund_order_12345",
  "reason": "Customer request"
}'

    • Response

      • {
  "status": {
    "error_code": "",
    "status": "SUCCESS",
    "message": "",
    "response_code": "",
    "operation_id": "4c1d9e2a-5b7f-4e3a-9d21-6f8a0b3c2e11"
  },
  "data": {
    "id": "refund_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "amount": 100,
    "payment": "payment_dd5c6fad1382b0622ec453207b0a7c31",
    "currency": "ZAR",
    "failure_reason": "",
    "metadata": {},
    "reason": "Customer request",
    "status": "Pending",
    "merchant_reference_id": "refund_order_12345",
    "payment_method_type": "za_scan_to_pay_ewallet"
  }
}
Retrieve payment (GET /v1/payments/{payment}) - after approved webhook

    • Request

      • curl -X GET 'https://sandboxapi.rapyd.net/v1/payments/payment_dd5c6fad1382b0622ec453207b0a7c31' \
  -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": "9e7b1c3d-2a4f-4b6e-8c0d-1f2a3b4c5d6e"
  },
  "data": {
    "id": "payment_dd5c6fad1382b0622ec453207b0a7c31",
    "amount": 300,
    "original_amount": 300,
    "is_partial": false,
    "currency_code": "ZAR",
    "country_code": "ZA",
    "status": "CLO",
    "description": "Order 12345",
    "merchant_reference_id": "order_12345",
    "customer_token": "cus_4d29a021beb3ba2a081ac1e84b5dd12f",
    "payment_method": "other_30498d78d580cea56ec98748b492cde5",
    "payment_method_data": {
      "id": "other_30498d78d580cea56ec98748b492cde5",
      "type": "za_scan_to_pay_ewallet",
      "category": "ewallet",
      "metadata": {},
      "next_action": "not_applicable"
    },
    "auth_code": null,
    "expiration": 1782389078,
    "captured": true,
    "refunded": false,
    "refunded_amount": 0,
    "redirect_url": "",
    "complete_payment_url": "https://merchant.example.com/success",
    "error_payment_url": "https://merchant.example.com/error",
    "created_at": 1781179477,
    "metadata": {},
    "failure_code": "",
    "failure_message": "",
    "paid": true,
    "paid_at": 1781179599,
    "visual_codes": {
      "Scan to Pay QR": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    },
    "textual_codes": {},
    "instructions": [
      {
        "name": "instructions",
        "steps": [
          {
            "step1": "On your mobile device, scan the QR code displayed on the checkout page using your preferred Scan to Pay app"
          },
          {
            "step2": "On mobile, select your preferred payment app from the dropdown to open the app"
          },
          {
            "step3": "Complete the payment in your selected payment app"
          }
        ]
      }
    ],
    "ewallet_id": "ewallet_ba37d302e173e089078bf8cbadf68cc8",
    "payment_method_type": "za_scan_to_pay_ewallet",
    "payment_method_type_category": "ewallet",
    "initiation_type": "customer_present",
    "next_action": "not_applicable",
    "error_code": ""
  }
}
En esta sección: