Skip to main content

Mobile Integration API Reference

Copy page

Copy page as Markdown for LLMs

Open in ChatGPT

Ask questions about this page

Anthropic

Open in Claude

Ask questions about this page

Mobile SDK integration allows merchants to accept in-app payments directly within their mobile applications. Amazon Payment Services provides native SDKs for Android, iOS, React Native, and Flutter platforms, enabling secure payment processing without redirecting users to external browsers.

Install the SDK​

Select your mobile platform to get started with Amazon Payment Services integration:

Android SDK

Native Android integration with Java/Kotlin support for secure in-app payments

iOS SDK

Native iOS integration with Swift/Objective-C support for seamless payment processing

React Native SDK

Cross-platform integration for React Native apps with unified payment experience

Flutter SDK

Cross-platform integration for Flutter apps with native performance

API Endpoints​

SDK Token Generation​

https://sbpaymentservices.payfort.com/FortAPI/paymentApi

SDK Token Generation​

Before processing any mobile payment, you must generate an SDK token on your backend server. This token authenticates your mobile app with Amazon Payment Services.

Request Format​

  • Method: POST
  • Content-Type: application/json
  • Submission: Server-to-server HTTPS POST

Request Parameters​

Parameter
service_command   String Max: 20 Required

Service command for SDK token generation.
Value: SDK_TOKEN
Example. SDK_TOKEN
access_code   String Max: 20 Required

Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings.
Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   String Max: 20 Required

Unique merchant identifier assigned by Amazon Payment Services during account setup.
Example. CycHZxVj
language   String Max: 2 Required

SDK language for UI elements and messages. Supported values: en (English) or ar (Arabic).
Example. en
device_id   String Max: 100 Required

Unique device identifier obtained from the mobile SDK.
Example. ffffffff-a9fa-0b44-7b27-29e70033c587
signature   String Max: 200 Required

SHA-256 hash signature for request authentication and integrity validation.
Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a

Response Parameters​

Parameter
service_command   String Max: 20

Service command from the request.
Value: SDK_TOKEN
Example. SDK_TOKEN
access_code   String Max: 20

Merchant access code used in the request.
Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   String Max: 20

Merchant identifier used in the request.
Example. CycHZxVj
language   String Max: 2

Language used for the SDK.
Example. en
device_id   String Max: 100

Device identifier from the request.
Example. ffffffff-a9fa-0b44-7b27-29e70033c587
signature   String Max: 200

Response signature for verification.
Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
sdk_token   String Max: 100

Generated SDK token for mobile payment processing.
Example. Dwp78q9
response_message   String Max: 150

Human-readable response description in requested language.
Example. Success
response_code   String Max: 5

Numeric response code indicating token generation result.
Example. 22000
status   String Max: 2

Two-digit status code indicating token generation state.
Example. 20

SDK tokens are single-use and expire after a short period. Generate a new token for each payment transaction and never reuse tokens.

SDK Token Sample Request
{
  "service_command": "SDK_TOKEN",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "language": "en",
  "device_id": "ffffffff-a9fa-0b44-7b27-29e70033c587",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
}
Sample Payment Response
{
  "service_command": "SDK_TOKEN",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "language": "en",
  "device_id": "ffffffff-a9fa-0b44-7b27-29e70033c587",
  "sdk_token": "Dwp78q9",
  "response_message": "Success",
    "response_code": "22000",
  "status": "20",
  "signature": "c63a266e5929c6c8b82c2d9f2c8ae5c2b1b6f8a9d7e4f3c2a1b0c9d8e7f6a5b4"
}
Sample Payment Request
{
  "command": "PURCHASE",
  "merchant_reference": "ORDER-123456",
  "amount": 10000,
  "currency": "AED",
  "language": "en",
  "customer_email": "customer@example.com",
  "sdk_token": "Dwp78q9",
  "payment_option": "VISA",
  "eci": "ECOMMERCE",
  "order_description": "Test Order",
  "customer_name": "John Doe",
  "customer_ip": "192.168.1.1"
}
Sample Payment Response
{
  "command": "PURCHASE",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "ORDER-123456",
  "amount": 10000,
  "currency": "AED",
  "language": "en",
  "customer_email": "customer@example.com",
  "fort_id": "149295435400084008",
  "payment_option": "VISA",
  "authorization_code": "P1000000000000372136",
  "response_message": "Success",
  "response_code": "14000",
  "status": "02",
  "card_number": "400555******0001",
  "expiry_date": "2105",
  "customer_name": "John Doe",
  "customer_ip": "192.168.1.1",
  "signature": "c63a266e5929c6c8b82c2d9f2c8ae5c2b1b6f8a9d7e4f3c2a1b0c9d8e7f6a5b4"
}

Payment Request Parameters​

Parameter
command   Alpha Max: 20 Required

Transaction command.
Possible values: AUTHORIZATION, PURCHASE
Example. PURCHASE
merchant_reference   Alphanumeric Max: 40 Required

The Merchant's unique order number.
Special characters: - _ .
Example. XYZ9239-yu898
amount   Numeric Max: 10 Required

The transaction's amount. Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example. 10000
currency   Alpha Max: 3 Required

The currency of the transaction's amount in ISO code 3.
Example. AED
language   Alpha Max: 2 Required

The checkout page and messages language.
Possible values: en / ar
Example. en
customer_email   Alphanumeric Max: 254 Required

The customer's email.
Special characters: _ - . @ +
Example. customer@domain.com
sdk_token   Alphanumeric Max: 100 Required

An SDK Token to enable using the Amazon Payment Services Mobile SDK.
Example. Dwp78q3
token_name   Alphanumeric Max: 100 Optional

The Token received from the Tokenization process.
Special characters: . @ - _
Example. Op9Vmp
payment_option   Alpha Max: 10 Optional

Payment option.
Possible values: MASTERCARD, VISA, AMEX, MADA, MEEZA
eci   Alpha Max: 16 Optional

Ecommerce indicator.
Possible values: ECOMMERCE
order_description   Alphanumeric Max: 150 Optional

A description of the order.
Special characters: ' / . _ - # : $ Space
Example. iPhone 6-S
statement_descriptor   Alphanumeric Max: 50 Optional

An Identifier used as description of the order.
Special characters: -
customer_ip   Alphanumeric Max: 45 Optional

It holds the customer's IP address. Mandatory if the fraud service is active. We support IPv4 and IPv6.
Special characters: . :
Example. 192.178.1.10
customer_name   Alpha Max: 40 Optional

The customer's name.
Special characters: _ \ / - . '
Example. John Smith
phone_number   Alphanumeric Max: 19 Optional

The customer's phone number.
Special characters: + - ( ) Space
Example. 00962797219966
settlement_reference   Alphanumeric Max: 22 Optional

The merchant submits unique value to Amazon Payment Services. The value is then passed to the acquiring bank and displayed to the merchant in the acquirer settlement file.
Example. XYZ9239-yu898
merchant_extra   Alphanumeric Max: 999 Optional

Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Special characters: . ; / _ - , ' @
Example. JohnSmith
merchant_extra1   Alphanumeric Max: 250 Optional

Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Special characters: . ; / _ - , ' @
Example. JohnSmith
merchant_extra2   Alphanumeric Max: 250 Optional

Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Special characters: . ; / _ - , ' @
Example. JohnSmith
merchant_extra3   Alphanumeric Max: 250 Optional

Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Special characters: . ; / _ - , ' @
Example. JohnSmith
merchant_extra4   Alphanumeric Max: 250 Optional

Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Special characters: . ; / _ - , ' @
Example. JohnSmith
merchant_extra5   Alphanumeric Max: 250 Optional

Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Special characters: . ; / _ - , ' @
Example. JohnSmith
agreement_id   Alphanumeric Max: 15 Optional

Identifier for the agreement with the payer to process payments to be used in recurring payments.
Do not use any special characters.
recurring_mode   Alphanumeric Max: 20 Optional

Indicates if the subsequent payments within the agreement has same/different amount or unscheduled.
Possible values: UNSCHEDULED, VARIABLE, FIXED
recurring_transactions_count   Alphanumeric Max: 100 Optional

The number of merchant-initiated payments within the recurring payment agreement.
Required if recurring_mode = VARIABLE or FIXED
recurring_expiry_date   Date Optional

The date where the merchant needs to end the recurring, the format is YYYY-MM-DD.
Example. 2024-10-05
recurring_days_between_payments   Numeric Optional

The number of days between payments agreed with the payer under your agreement with them.

Multiply your transaction amount by the currency decimal code per ISO code 3 before sending the amount parameter. For currencies with three-decimal codes, round VISA transactions to zero in the final decimal place to avoid declined transactions. Example: For 500 AED (2 decimal places per ISO code 3), multiply by 100 to send 50000 in your request.

The merchant_reference must be unique per transactions.

Payment Response Parameters​

Parameter
command   Alpha Max: 20

Transaction command.
Possible values: AUTHORIZATION, PURCHASE
Example. PURCHASE
merchant_reference   Alphanumeric Max: 40

The Merchant's unique order number.
Example. XYZ9239-yu898
amount   Numeric Max: 10

The transaction's amount. Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example. 10000
currency   Alpha Max: 3

The currency of the transaction's amount in ISO code 3.
Example. AED
customer_email   Alphanumeric Max: 254

The customer's email.
Example. customer1@domain.com
fort_id   Numeric Max: 20

The order's unique reference returned by our system.
Example. 149295435400084008
sdk_token   Alphanumeric Max: 100

An SDK Token to enable using the Amazon Payment Services Mobile SDK.
Example. Dwp78q3
token_name   Alphanumeric Max: 100

The Token received from the Tokenization process.
Example. Op9Vmp
payment_option   Alpha Max: 10

Payment option.
Possible values: MASTERCARD, VISA, AMEX, MADA, MEEZA
eci   Alpha Max: 16

The E-commerce indicator.
Possible values: ECOMMERCE
authorization_code   Alphanumeric Max: 100

The authorization code returned from the 3rd party.
Example. P1000000000000372136
order_description   Alphanumeric Max: 150

It holds the description of the order.
Example. iPhone 6-S
statement_descriptor   Alphanumeric Max: 50

An Identifier used as description of the order.
Special characters: -
response_message   Alphanumeric Max: 150

The message description of the response code; it returns according to the request language.
response_code   Numeric Max: 5

Response Code carries the value of our system's response. The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages.
Example. 14000
customer_ip   Alphanumeric Max: 45

It holds the customer's IP address. We support IPv4 and IPv6.
Example. 192.178.1.10
customer_name   Alpha Max: 40

The customer's name.
Example. John Smith
expiry_date   Numeric Max: 4

The card's expiry date.
Example. 2105
card_number   Numeric Max: 16

The masked credit card's number. Only the MEEZA payment option takes 19 digits card number. AMEX payment option takes 15 digits card number. Otherwise, they take 16 digits card number.
Example. 400555*****0001
status   Numeric Max: 2

A two-digit numeric value that indicates the status of the transaction.
phone_number   Alphanumeric Max: 19

The customer's phone number.
Example. 00962797219966
settlement_reference   Alphanumeric Max: 22

The merchant submits unique value to Amazon Payment Services. The value is then passed to the acquiring bank and displayed to the merchant in the acquirer settlement file.
Example. XYZ9239-yu898
merchant_extra   Alphanumeric Max: 999

Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example. JohnSmith
merchant_extra1   Alphanumeric Max: 250

Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example. JohnSmith
merchant_extra2   Alphanumeric Max: 250

Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example. JohnSmith
merchant_extra3   Alphanumeric Max: 250

Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example. JohnSmith
merchant_extra4   Alphanumeric Max: 250

Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example. JohnSmith
merchant_extra5   Alphanumeric Max: 250

Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example. JohnSmith
agreement_id   Alphanumeric Max: 15

Identifier for the agreement with the payer to process payments to be used in recurring payments.
Do not use any special characters.

Response Codes​

For a complete list of response codes and their descriptions, please refer to our Error Codes Documentation.

Testing The Integration​

Sandbox Testing​

  • SDK Token URL: https://sbpaymentservices.payfort.com/FortAPI/paymentApi
  • Test Cards: Use our comprehensive Testing Cards

Go-Live Process​

When ready to move to production, follow our Go-Live checklist

Was this page helpful?

Thanks for your feedback!