Setup Your Server

Your server plays a crucial role in initializing mobile payment sessions. In our integration, there's only one endpoint that your merchant server needs to handle: /mobile/init. This endpoint validates the request by checking the signature and other required parameters, then returns a response that enables further payment processing. The behaviour of the Merchant Server below is valid in both iOS SDK and Android SDK cases.

Endpoint

Method: POST
Path:

• 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. It contains several required parameters to establish the payment session, along with optional parameters for additional contextual data.

Required Parameters

• 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)
  The bundle identifier of your merchant’s application.

🚧

app_bundle_id

iOS SDK: Set the expected bundle identifier for your iOS app to match the one used during the build. If this value doesn't align at the SDK runtime, a security warning is raised. For security purposes, avoid hardcoding the Bundle ID directly in the app. Instead, store it securely on a server, send it in the /mobile/init request, and configure it dynamically.

Android SDK: Fill the app_bundle_id field with the AppSignature value — the SHA256 fingerprint of the certificate used to sign the app. To ensure security, do not hardcode the fingerprint within the app; it should be stored on a server, retrieved dynamically at runtime, and then set in this field during initialization.

Optional Parameters

• notification_url (string)
  URL where notifications about the transaction status can be sent.

• order_id (string)
  Identifier for the order.

• gender (string)

• salutation (string)

• title (string)

• customer_id (string)

• customer_ip (string)

• first_name (string)

• last_name (string)

• birthday (string)

• street (string)

• house (string)

• zip (string)

• city (string)

• country (string)

• postbox (string)

• state (string)

• phone (string)

• fax (string)

• mobile (string)

• custom1 (string)

• custom2 (string)

• custom3 (string)

Sample Request

Below is an example of a typical request payload:

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

📘

Note

When performing a zero-amount authorization, replace "42" with "0" in the "amount" field.

Response Format

The response from the /mobile/init endpoint is returned as JSON. It indicates whether the initialization is successful or if an error occurred.

Successful Response

If the request is successful (i.e., status equals 0), you will receive the following data:

• status (integer)
  0 indicates a successful request.

• session_id (string)
  A unique session identifier for the payment.

• ephemeral_key (string)
  A temporary key used for further API calls during the payment process.

• transaction_id (integer)
  The unique identifier for the initiated transaction.

Example Successful Response

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

Error Response

In the event of an error (status equals -1), the response includes:

• status (integer)
  -1 indicates an error occurred.

• error_code (integer)
  A code that identifies the type of error.

• error_message (string)
  A descriptive message explaining the error.

Zero Amount Request Example

For a zero amount authorization, the request should include "amount": "0" alongside the other required parameters:

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