Skip to main content

Documentation

Mobicred Connector

Connector overview

Connector name: Mobicred
Payment method type: za_mobicred_ewallet. Mobicred buy-now-pay-later credit account (South Africa). Category ewallet. Customer logs in with Mobicred username and password, then confirms with an SMS OTP on a Rapyd-hosted page.
Gateway name: mobicred (direct Rapyd to Mobicred REST API, form-encoded requests to Mobicred endpoint)
Supported countries and currencies: South Africa (ZA), ZAR
Every payment needs a customer OTP step: an SMS OTP is sent, and the customer enters it on the Rapyd-hosted OTP page (redirect_url).
Capture and cancel are not available for this payment method.
Installments are decided by Mobicred's credit engine. The merchant does not configure them.

Note

The customer enters the OTP sent by Mobicred to complete the payment. The OTP is valid for about 10 minutes and needs to be entered correctly; if it is not accepted, the customer can simply start again with a new payment. A payment that is not completed after the OTP step expires automatically.

Capabilities

API request	Endpoint	Unique capabilities	Limitations
Create payment	`POST /v1/payments`	Customer Mobicred username and password are sent in `payment_method.fields.` Returns status ACT, next_action pending_confirmation and redirect_url to the Rapyd-hosted OTP page (otp_length=6). metadata is passed to Mobicred as cCustomField.	Do not send capture; it does not apply to this payment method.
Customer OTP verification / resend (Rapyd-hosted page)	N/A - customer action on redirect_url, not a merchant API	OTP submit -> purPreAuth; resend -> purOTP. Result: CLO when Mobicred approves the purchase (code 101).	The OTP is valid for about 10 minutes; after that, create a new payment.
Create refund	`POST /v1/refunds`	Full and partial refunds (purRefund), synchronous result.	Cannot exceed purchase balance
Retrieve payment	`GET /v1/payments/{payment}`	The connector can query Mobicred (purQuery) and map pcPurchaseState to Rapyd status.	-

Header parameters: Standard Rapyd headers. No connector-specific headers.
Supported workflows
- eWallet payment with customer redirect for OTP.
- Create payment (status ACT, next_action pending_confirmation) -> redirect customer to redirect_url -> customer enters OTP -> payment closes (CLO) when Mobicred approves the purchase.
- Unique: customer credentials (Mobicred username/password) are collected at payment creation, then an SMS OTP is confirmed on a Rapyd-hosted page.

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	-	Positive amount in ZAR	Decimal amount, not cents. Sent to Mobicred as dAmount (string of the decimal amount).	Purchase amount.	1500.00	Merchant
`currency`	-	string	Required	-	ZAR	ZAR only.	Payment currency.	ZAR	Merchant
`payment_method`	-	object	Required	-	-	-	Payment method object.	-	Merchant
`type`	`payment_method`	string	Required	-	`za_mobicred_ewallet`	-	Payment method type.	`za_mobicred_ewallet`	Merchant
`username`	`payment_method.fields`	string	Required	-	-	Customer's Mobicred login. Display above the password field.	Customer's Mobicred account username (often the account email).	customer@example.com	Merchant (entered by customer)
`password`	`payment_method.fields`	string	Required	-	-	Sensitive. Must be masked in any UI (input type=password). Never log or store.	Customer's Mobicred account password.	<customer-mobicred-password>	Merchant (entered by customer)
`capture`	-	boolean	Optional	Not set	Do not send for this payment.	Not applicable to this payment method.	Card-only flag in Rapyd. Must be omitted for `za_mobicred_ewallet`.	(omit)	Merchant
`metadata`	-	object	Optional	-	Any JSON object	-	Merchant metadata.	{"order_ref": "ORD-1001"}	Merchant
`merchant_reference_id`	-	string	Optional	-	-	Rapyd limit applies. NOT sent to Mobicred.	Merchant's own order reference.	ORD-1001	Merchant
`description`	-	string	Optional	-	-	-	Payment method description.	Order ORD-1001	Merchant
`complete_payment_url`	-	string	Optional	-	Valid URL	-	URL the customer returns to after a completed payment.	https://merchant.example.com/success	Merchant
`error_payment_url`	-	string	Optional	-	Valid URL	-	URL the customer returns to if the payment is not completed.	https://merchant.example.com/error	Merchant
`expiration`	-	number	Optional	Payment default	Unix timestamp	Payment is expirable.	Payment expiration. When the payment expires, its status becomes EXP.	1767225600	Merchant
`customer`	-	string or object	Optional	-	Rapyd customer ID (cus_) or inline customer object	-	Shopper details. Not read by the Mobicred connector.	cus_1a2b3c234234243	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_0f2c...	Rapyd
`status`	`data`	string	ACT, CLO, ERR	Payment status after purCreate.	ACT	Rapyd (from Gateway code)
`redirect_url`	`data`	string	-	Rapyd-hosted OTP page. Redirect the customer here to enter the SMS OTP.	https://<otp-host>/mobicred?payment_token=<rapyd_token>&otp_length=6	Rapyd
`next_action`	`data`	string	pending_confirmation, not_applicable	pending_confirmation while the customer still has to enter the OTP; not_applicable after a successful OTP.	pending_confirmation	Rapyd
`captured`	`data`	boolean	true, false	Whether the payment is captured.	false	Rapyd
`paid`	`data`	boolean	true, false	Whether the payment is paid.	false	Rapyd
`failure_code`	`data`	string	Mobicred piResponseCode as string (e.g. 201, 202, 206, 207, 320)	Mobicred response code.	202	Gateway
`failure_message`	`data`	string	Mobicred pcReason or standard reason text	Mobicred response text.	Incorrect Password	Gateway
`payment_method_type`	`data`	string	`za_mobicred_ewallet`	Payment used.	`za_mobicred_ewallet`	Rapyd
`payment_method_data`	`data`	object	-	Payment method details. username/password must not be exposed.	{"type": "`za_mobicred_ewallet`", "category": "ewallet"}	Rapyd
`textual_codes`	`data`	object	-	Not populated by the connector.	{}	Rapyd

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_ id	Payment must be completed (CLO).	ID of the payment to refund.	payment_0f2c23423423	Merchant
`amount`	-	number	Optional	Full remaining amount	-	Up to the purchase balance; Mobicred code 319 if exceeded.	Refund amount (partial allowed).	500.00	Merchant
`reason`	-	string	Optional	Refund	-	-	Refund reason.	Merchandise returned	Merchant
`merchant_reference_id`	-	string	Optional	-	-	Not sent to Mobicred.	Merchant refund reference.	REF-1001	Merchant
`currency`	-	string	Optional	Payment currency	ZAR	-	Refund currency.	ZAR	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_7a1b...	Rapyd
`status`	`data`	string	Completed, Error	Refund status.	Completed	Rapyd (from Gateway code)
`amount`	`data`	number	-	Refunded amount.	500.00	Rapyd
`payment_method_type`	`data`	string	`za_mobicred_ewallet`	Payment.	`za_mobicred_ewallet`	Rapyd
`failure_reason`	`data`	string	-	Reason text from Mobicred.	Gateway

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	-	payment_ id	-	ID of the payment to retrieve.	payment_0f2cwerwr24	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`	`data`	string	ACT, CLO, CAN, ERR	Current status.	CLO	Rapyd (from Gateway state)
`paid`	`data`	boolean	-	Paid flag.	true	Rapyd
`failure_code`	`data`	string	-	Mobicred response code.	406	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.

For Mobicred, only setTransaction (Rapyd hosted checkout) with TransactionType PAYMENT is supported.

Field mapping (Rapyd field to original PayU field)

Create Payment - Body parameters

Rapyd field name	Original PayU field
`amount`	`Basket/amountInCents` (setTransaction; cents are converted to major units)
`currency`	`Basket/currencyCode` (falls back to the merchant's configured default currency)
`payment_method`	`AdditionalInformation/supportedPaymentMethods`
`type`	`AdditionalInformation/supportedPaymentMethods` = MOBICRED
`username`	On setTransaction the shopper enters Mobicred credentials on the Rapyd hosted page.
`password`	On setTransaction the shopper enters Mobicred credentials on the Rapyd hosted page.
`capture`	`TransactionType` (PAYMENT)
`metadata`	None - merchant metadata has no PayU source
`merchant_reference_id`	`AdditionalInformation/merchantReference`
`description`	`Basket/description`
`complete_payment_url`	`AdditionalInformation/returnUrl` (complete_checkout_url on setTransaction)
`error_payment_url`	`AdditionalInformation/cancelUrl` (also `cancel_checkout_url` on setTransaction)
`expiration`	-
`customer`	`Customer/email`, `Customer/firstName`, `Customer/lastName`, `Customer/mobile` (+ `Customer/countryCode` as dialing code)

Accepted values mapping

Field name	Original PayU value	Rapyd value
`payment_method.type`	MOBICRED	`za_mobicred_ewallet`
`capture`	TransactionType PAYMENT	(capture omitted)

Create Payment - Response parameters

Rapyd field name	Original PayU field
`id`	`payUReference`
`status`	`transactionState`
`redirect_url`	/rpp.do?payUReference=... (setTransaction response; the shopper reaches the Rapyd OTP page from the hosted checkout)
`next_action`	None
`captured`	None
`paid`	`successful`
`failure_code`	`resultCode`
`failure_message`	`resultMessage` / `displayMessage`
`payment_method_type`	`paymentMethodsUsed` (MOBICRED entry: method, `amountInCents`)
`payment_method_data`	`paymentMethodsUsed`
`textual_codes`	None

Accepted values mapping

Field name	Original PayU value	Rapyd value
`status`	Mobicred code 1-4 (Created / OTP sent / Pre-authorized)	ACT
`status`	Mobicred code 101-103 (Approved / Cancelled / Refunded OK)	CLO
`status`	Any other code	ERR
`status`	SUCCESSFUL (resultCode 00)	CLO
`status`	PROCESSING	ACT
`status`	FAILED (resultCode 05, pointOfFailure ACQUIRER)	ERR
`status`	EXPIRED (resultCode P015)	CAN
`status`	EXPIRED (resultCode 994)	EXP

Create Refund - Body parameters

Rapyd field name	Original PayU field
`payment`	`AdditionalInformation/payUReference` (doTransaction CREDIT; resolved to the stored Rapyd payment)
`amount`	`Basket/amountInCents` (converted to major units; refundable balance tracked in `payu_africa_transactions`)
`reason`	-
`merchant_reference_id`	`AdditionalInformation/merchantReference`
`currency`	`Basket/currencyCode`

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`	`payUReference` (refund gets its own `PayUReference`; `original_payu_reference` kept in metadata)
`status`	`transactionState` / `successful`
`amount`	`Basket/amountInCents`
`payment_method_type`	None
`failure_reason`	`resultMessage`

Accepted values mapping

Field name	Original PayU value	Rapyd value
`status`	Mobicred code 103	Completed (CLO)
`status`	Any other code	Error (ERR)

Retrieve Payment - Path parameters

Rapyd field name	Original PayU field
`payment`	`payUReference` (getTransaction; lookup by `merchantReference` not yet supported)

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`	`transactionState`
`paid`	`successful`
`failure_code`	`resultCode`

Accepted values mapping

Field name	Original PayU value	Rapyd value
`status`	pcPurchaseState Approved / Paid Up	CLO
`status`	pcPurchaseState Cancelled	CAN
`status`	pcPurchaseState Declined	ERR
`status`	pcPurchaseState Created / Pre-Authorized	ACT

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-raw '{
    "amount": 1500.00,
    "currency": "ZAR",
    "merchant_reference_id": "ORD-1001",
    "description": "Order ORD-1001",
    "complete_payment_url": "https://merchant.example.com/success",
    "error_payment_url": "https://merchant.example.com/error",
    "metadata": { "order_ref": "ORD-1001" },
    "payment_method": {
      "type": "za_mobicred_ewallet",
      "fields": {
        "username": "customer@example.com",
        "password": "<customer-mobicred-password>"
      }
    }
  }'

Response

{
  "status": {
    "error_code": "",
    "status": "SUCCESS",
    "message": "",
    "response_code": "",
    "operation_id": "<operation-id>"
  },
  "data": {
    "id": "payment_0f2c4e6a8b0d2f4a6c8e0a2c4e6a8b0d",
    "amount": 0,
    "original_amount": 1500,
    "currency_code": "ZAR",
    "country_code": "ZA",
    "status": "ACT",
    "merchant_reference_id": "ORD-1001",
    "description": "Order ORD-1001",
    "payment_method_type": "za_mobicred_ewallet",
    "payment_method_type_category": "ewallet",
    "payment_method_data": {
      "type": "za_mobicred_ewallet",
      "category": "ewallet",
      "metadata": {}
    },
    "captured": false,
    "paid": false,
    "next_action": "pending_confirmation",
    "redirect_url": "https://<otp-host>/mobicred?payment_token=<rapyd_token>&otp_length=6",
    "complete_payment_url": "https://merchant.example.com/success",
    "error_payment_url": "https://merchant.example.com/error",
    "failure_code": "",
    "failure_message": "",
    "textual_codes": {},
    "instructions": [],
    "metadata": {
      "order_ref": "ORD-1001"
    }
  }
}

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-raw '{
    "payment": "payment_0f2c4e6a8b0d2f4a6c8e0a2c4e6a8b0d",
    "amount": 500.00,
    "reason": "Merchandise returned",
    "merchant_reference_id": "REF-1001"
  }'

Response

{
  "status": {
    "error_code": "",
    "status": "SUCCESS",
    "message": "",
    "response_code": "",
    "operation_id": "<operation-id>"
  },
  "data": {
    "id": "refund_7a1b3c5d7e9f1a3b5c7d9e1f3a5b7c9d",
    "amount": 500,
    "payment": "payment_0f2c4e6a8b0d2f4a6c8e0a2c4e6a8b0d",
    "currency": "ZAR",
    "reason": "Merchandise returned",
    "status": "Completed",
    "failure_reason": "",
    "merchant_reference_id": "REF-1001",
    "payment_method_type": "za_mobicred_ewallet",
    "metadata": {}
  }
}

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

Request

curl -X GET 'https://sandboxapi.rapyd.net/v1/payments/payment_0f2c4e6a8b0d2f4a6c8e0a2c4e6a8b0d' \
  -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": "<operation-id>"
  },
  "data": {
    "id": "payment_0f2c4e6a8b0d2f4a6c8e0a2c4e6a8b0d",
    "amount": 1500,
    "original_amount": 1500,
    "currency_code": "ZAR",
    "country_code": "ZA",
    "status": "CLO",
    "captured": true,
    "paid": true,
    "merchant_reference_id": "ORD-1001",
    "payment_method_type": "za_mobicred_ewallet",
    "payment_method_type_category": "ewallet",
    "next_action": "not_applicable",
    "redirect_url": "",
    "failure_code": "",
    "failure_message": ""
  }
}

In this section: