Setup Your Server

Your server plays a crucial role in mobile payments: it creates the payment session that your app uses to launch any payment flow. Only one call is required — your server sends a POST request to payabl.'s /mobile/init endpoint, receives session credentials, and passes them to your app.

The same server setup works for both the iOS SDK and the Android SDK.

How it fits together

Your app asks your server to start a payment (e.g., when the customer taps Pay).
Your server calls /mobile/init with the transaction details and a request signature.
payabl. validates the request and returns a session_id and ephemeral_key.
Your server passes both values to your app, which uses them to launch the SDK payment flow.

⚠️
Call /mobile/init from your server only — never from your app. The request signature is generated with your merchant secret, which must never be embedded in a mobile app. Anything shipped inside an app binary can be extracted.

Endpoint

Method: POST

Environment	URL
Sandbox	`https://pay4.sandbox.payabl.com/pay/mobile/init`
Production	`https://pay4.payabl.com/pay/mobile/init`

Request format

The request is sent as a JSON payload.

Required parameters

Parameter	Type	Description
`merchant_id`	string	Unique identifier for your merchant account.
`amount`	string	The transaction amount. For zero-amount authorization, set the value to `"0"`.
`currency`	string	Currency code for the transaction (e.g., `"EUR"`, `"USD"`).
`signature`	string	A secure signature generated using your merchant secret. This ensures the integrity of the request.
`email`	string	The customer's email address.
`app_bundle_id`	string	Identifies your app to the payment gateway. The expected value differs by platform — see below.

🚧
app_bundle_id — platform-specific values
iOS SDK: Set the bundle identifier of your iOS app (e.g., com.yourcompany.yourapp), matching the one used during the build. If this value doesn't match at SDK runtime, a security warning is raised.
Android SDK: Set the AppSignature value — the SHA-256 fingerprint of the certificate used to sign your app.
Both platforms: Do not hardcode this value in your app. Store it on your server and include it in the /mobile/init request, so the SDK receives it dynamically at runtime.

Conditionally required parameters

Some parameters are required only when the payment session will offer specific payment methods. If they are missing, the affected payment method will fail even though the /mobile/init call may succeed.

Apple Pay & Google Pay

Parameter	Type	Description
`country`	string	The customer's country code. Required for Apple Pay and Google Pay sessions.

Instant Bank Transfer

If the payment session will offer Instant Bank Transfer (standalone or via the Hosted Checkout Page), the following parameters are required, even though they are optional for other payment methods:

Parameter	Type	Description
`app_schema`	string	Your app's custom URL scheme for deep linking (e.g., `"payabl"`, `"yourapp"`). If not specified, the backend returns an error. Must match your app's deep link configuration.
`url_success`	string	Redirect after a successful payment.
`url_failed`	string	Redirect after a failed or cancelled payment.
`url_return`	string	Generic redirect URL.
`notification_url`	string	Server-to-server webhook for final payment confirmation. Must be an HTTPS URL.

Apart from notification_url, the redirect URLs can use your custom scheme (e.g., payabl://payment-callback/success) or App Links / Universal Links (e.g., https://yourdomain.com/payment-callback/success).

{
  "app_schema": "payabl",
  "url_success": "payabl://payment-callback/success",
  "url_failed": "payabl://payment-callback/failed",
  "url_return": "https://yourdomain.com/payment-callback/return",
  "notification_url": "https://your-server.com/api/webhook"
}

📘
The redirect URLs must match your app's deep link configuration. See the platform setup guides: Instant Bank Transfer (iOS) | Instant Bank Transfer (Android).

Optional parameters

These parameters are optional for all payment methods, except where flagged. Parameters that only apply to specific payment methods (such as the Instant Bank Transfer redirect URLs) are documented in the conditionally required section above and are not repeated here.

Parameter	Type	Description
`notification_url`	string	URL where notifications about the transaction status are sent.
`order_id`	string	Your identifier for the order.
`customer_id`	string	Your identifier for the customer.
`customer_ip`	string	The customer's IP address.
`first_name`, `last_name`	string	Customer name.
`gender`, `salutation`, `title`, `birthday`	string	Additional customer details.
`street`, `house`, `zip`, `city`, `state`, `postbox`	string	Customer address.
`country`	string	The customer's country code. Required for Apple Pay and Google Pay — see conditionally required parameters above.
`phone`, `mobile`, `fax`	string	Customer contact numbers.
`custom1`, `custom2`, `custom3`	string	Free-form fields returned with the transaction.

Sample request

{
  "amount": "42",
  "currency": "EUR",
  "merchant_id": "merchant_user_test",
  "order_id": "Payabl test",
  "email": "[email protected]",
  "app_bundle_id": "338as7df61l32k0a9ufdag9659as8dff",
  "signature": "1a29075414d8061aa1e9ef6eb4f20a69dc0f2f36"
}

📘
Zero-amount authorization: to authorize without charging (e.g., card verification), send "amount": "0" alongside the same required parameters.

Response format

The response is returned as JSON.

Successful response

If the request is successful, status equals 0 and the response contains:

Field	Type	Description
`status`	integer	`0` indicates a successful request.
`session_id`	string	A unique session identifier for the payment. Pass this to your app.
`ephemeral_key`	string	A temporary key used during the payment process. Pass this to your app.
`transaction_id`	integer	The unique identifier for the initiated transaction. Store this to reconcile the payment result.

{
  "session_id": "072c7e2ceb942912bb655006c01ad3cfc37c5a29",
  "status": 0,
  "ephemeral_key": "26d917207b1f36ae83789b24b7de1f3e4e0b10eb",
  "transaction_id": 215517862
}

Error response

If an error occurs, status equals -1 and the response contains:

Field	Type	Description
`status`	integer	`-1` indicates an error occurred.
`error_code`	integer	A code identifying the type of error — look it up in the Error Code Reference.
`error_message`	string	A descriptive message explaining the error.

📘
See the Error Code Reference for the full catalog of error codes, their causes, and how to resolve them.

Setup Your Server

How it fits together

Call `/mobile/init` from your server only — never from your app. The request signature is generated with your merchant secret, which must never be embedded in a mobile app. Anything shipped inside an app binary can be extracted.

Endpoint

Request format

Required parameters

`app_bundle_id` — platform-specific values

Conditionally required parameters

Apple Pay & Google Pay

Instant Bank Transfer

The redirect URLs must match your app's deep link configuration. See the platform setup guides: Instant Bank Transfer (iOS) | Instant Bank Transfer (Android).

Optional parameters

Sample request

Zero-amount authorization: to authorize without charging (e.g., card verification), send `"amount": "0"` alongside the same required parameters.

Response format

Successful response

Error response

See the Error Code Reference for the full catalog of error codes, their causes, and how to resolve them.

What’s Next

How it fits together

Call /mobile/init from your server only — never from your app. The request signature is generated with your merchant secret, which must never be embedded in a mobile app. Anything shipped inside an app binary can be extracted.

Endpoint

Request format

Required parameters

app_bundle_id — platform-specific values

Conditionally required parameters

Apple Pay & Google Pay

Instant Bank Transfer

The redirect URLs must match your app's deep link configuration. See the platform setup guides: Instant Bank Transfer (iOS) | Instant Bank Transfer (Android).

Optional parameters

Sample request

Zero-amount authorization: to authorize without charging (e.g., card verification), send "amount": "0" alongside the same required parameters.

Response format

Successful response

Error response

See the Error Code Reference for the full catalog of error codes, their causes, and how to resolve them.

What’s Next

Call `/mobile/init` from your server only — never from your app. The request signature is generated with your merchant secret, which must never be embedded in a mobile app. Anything shipped inside an app binary can be extracted.

`app_bundle_id` — platform-specific values

Zero-amount authorization: to authorize without charging (e.g., card verification), send `"amount": "0"` alongside the same required parameters.