Skip to main content

Documentación

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), which triggers pre-authorization.
Installments are decided by Mobicred's credit engine. The merchant does not configure them.

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 with redirect_url to the Rapyd-hosted OTP page (otp_length=6). metadata is passed to Mobicred as cCustomField.	Do not send capture (Rapyd rejects it for ewallet).
Customer OTP verification / resend (Rapyd-hosted page)	N/A - customer action on redirect_url, not a merchant API	OTP submit -> purPreAuth; resend -> purOTP. Result: ACT (pre-authorized) or CLO if Mobicred returns 101.	OTP usually expires after about 10 minutes (code 209). Max wrong attempts (210) and max resends (211) fail the payment.
Capture payment	`POST /v1/payments/{payment}/capture`	Completes a pre-authorized Mobicred purchase (purApprove). Needed after OTP in the current setup.	Full capture only.
Cancel payment	`DELETE /v1/payments/{payment}`	Voids the purchase (purCancel) with fixed reason 'User Requested'.	Always cancels the full amount.
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 special headers.
Supported workflows
- eWallet payment with customer redirect for OTP.
- Create payment (status ACT) -> redirect customer to redirect_url -> customer enters OTP -> payment ACT (pre-authorized) -> merchant captures -> CLO.
- 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

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	-	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.	Rapyd rejects capture (true or false) for any non-card category with ERROR_CREATE_PAYMENT_CAPTURE_FOR_CARD_METHODS_ONLY.	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 after a failed payment.	https://merchant.example.com/error	Merchant
`expiration`	-	number	Optional	Payment default	Unix timestamp	Payment is expirable: min 0 s, max 1209600 s (14 days).	Payment expiration.	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

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_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	redirect	Next step for the customer.	redirect	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 error code on failure.	202	Gateway
`failure_message`	`data`	string	Mobicred pcReason or standard reason text	Failure reason.	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

Capture 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	-	payment_ id	Payment must be ACT (pre-authorized after OTP).	ID of the payment to capture.	payment_0f2c234243234	Merchant
`amount`	-	number	Optional	Full amount	-	Partial capture not supported.	Amount to capture.	(omit)	Merchant

Capture 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
`status`	`data`	string	CLO, ERR	Payment status after capture.	CLO	Rapyd (from Gateway code)
`captured`	`data`	boolean	true	Captured flag.	true	Rapyd
`paid`	`data`	boolean	true	Paid flag.	true	Rapyd
`failure_code`	`data`	string	Mobicred code	Error code on failure.	403	Gateway

Cancel 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	-	payment_ id	Payment should be ACT (created or pre-authorized, not captured).	ID of the payment to cancel.	payment_0f2c...	Merchant

Cancel 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
`status`	`data`	string	CAN, ERR	Status after cancel.	CAN	Rapyd (from Gateway code)
`failure_code`	`data`	string	Mobicred code	Error code on failure.	313	Gateway
`failure_message`	`data`	string	-	Error reason.	MCReference not valid	Gateway

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_ id	Payment must be captured (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

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_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 on failure	Cannot refund more than purchase balance	Gateway

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	-	payment_ id	-	ID of the payment to retrieve.	payment_0f2cwerwr24	Merchant

Retrieve 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
`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 code when Declined.	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.

Field mapping (Rapyd field to original PayU field)

Create Payment - Body parameters

Rapyd field name	Original PayU field
`amount`	`Basket/amountInCents` (setTransaction and doTransaction PAYMENT; 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 types Mobicred credentials on the Rapyd hosted page; doTransaction PAYMENT sends empty `payment_method.fields` for every APM except MASTERPASS, so no Magellan element carries Mobicred credentials.
`password`	On setTransaction the shopper types Mobicred credentials on the Rapyd hosted page; doTransaction PAYMENT sends empty `payment_method.fields` for every APM except MASTERPASS, so no Magellan element carries Mobicred credentials.
`capture`	`TransactionType` (PAYMENT / RESERVE)
`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; `complete_payment_url` on doTransaction)
`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)
`capture`	TransactionType RESERVE	capture=false (card-only pages)

Create Payment - Response parameters

Rapyd field name	Original PayU field
`id`	`payUReference`
`status`	`transactionState`
`redirect_url`	redirect (doTransaction response) / /rpp.do?`payUReference`=... (setTransaction)
`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 (e.g. 201 Invalid Username, 202 Incorrect Password, 206 Arrears, 207 Insufficient Funds, 320 Invalid IP)	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

Capture Payment - Path parameters

Rapyd field name	Original PayU field
`payment`	-
`amount`	-

Accepted values mapping

Field name	Original PayU value	Rapyd value
`operation`	TransactionType FINALIZE	`POST /v1/payments/{payment}/capture`

Capture Payment - Response parameters

Rapyd field name	Original PayU field
`status`	`transactionState`
`captured`	None
`paid`	`successful`
`failure_code`	`resultCode`

Cancel Payment - Path parameters

Rapyd field name	Original PayU field
`payment`	-

Accepted values mapping

Field name	Original PayU value	Rapyd value
`operation`	TransactionType RESERVE_CANCEL	`DELETE /v1/payments/{payment}`

Cancel Payment - Response parameters

Rapyd field name	Original PayU field
`status`	`transactionState`
`failure_code`	`resultCode`
`failure_message`	`resultMessage`

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": "redirect",
    "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"
    }
  }
}

Capture payment (`POST /v1/payments/{payment}/capture`)

Request

curl -X POST 'https://sandboxapi.rapyd.net/v1/payments/payment_0f2c4e6a8b0d2f4a6c8e0a2c4e6a8b0d/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-raw '{}'

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",
    "status": "CLO",
    "captured": true,
    "paid": true,
    "payment_method_type": "za_mobicred_ewallet",
    "next_action": "not_applicable",
    "failure_code": "",
    "failure_message": ""
  }
}

Cancel payment (`DELETE /v1/payments/{payment}`)

Request

curl -X DELETE '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": 0,
    "original_amount": 1500,
    "currency_code": "ZAR",
    "status": "CAN",
    "captured": false,
    "paid": false,
    "payment_method_type": "za_mobicred_ewallet",
    "failure_code": "",
    "failure_message": ""
  }
}

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

En esta sección: