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

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

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

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

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

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_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": ""
  }
}

In this section:

Documentation

Scan to Pay Connector

Connector overview

Capabilities

Field mapping tables

Create Payment - Body parameters

Note

Create Payment - Response parameters

Note

Create Refund - Body parameters

Note

Create Refund - Response parameters

Note

Retrieve Payment - Path parameters

Note

Migrating from PayU

Migration notes

Field mapping (Rapyd field to original PayU field)

Create Payment - Body parameters

Accepted values mapping

Create Payment - Response parameters

Accepted values mapping

Create Refund - Body parameters

Accepted values mapping

Create Refund - Response parameters

Accepted values mapping

Retrieve Payment - Path parameters

API samples

Create payment (`POST /v1/payments`)

Create refund (`POST /v1/refunds`)

Retrieve payment (`GET /v1/payments/{payment}`) - after approved webhook

Search results

Documentation

Scan to Pay Connector

Connector overview

Capabilities

Field mapping tables

Create Payment - Body parameters

Note

Create Payment - Response parameters

Note

Create Refund - Body parameters

Note

Create Refund - Response parameters

Note

Retrieve Payment - Path parameters

Note

Migrating from PayU

Migration notes

Field mapping (Rapyd field to original PayU field)

Create Payment - Body parameters

Accepted values mapping

Create Payment - Response parameters

Accepted values mapping

Create Refund - Body parameters

Accepted values mapping

Create Refund - Response parameters

Accepted values mapping

Retrieve Payment - Path parameters

API samples

Create payment (POST /v1/payments)

Create refund (POST /v1/refunds)

Retrieve payment (GET /v1/payments/{payment}) - after approved webhook

Search results

Create payment (`POST /v1/payments`)

Create refund (`POST /v1/refunds`)

Retrieve payment (`GET /v1/payments/{payment}`) - after approved webhook