Accept Payments
Pay/Authorize
Authorize allows you to place a hold on a specific amount on the customer’s account. Pay is the service that allows you to charge a customer a specific amount for the services and goods sold to him/her.
Transaction Flow
- The merchant sends the payment request with the payment details.
- MAF Pay processes the payment and then responds back to the merchant with the payment response.
Note: In case your account has 3Ds service active and the customer card is 3Ds enrolled you have to redirect the customer to the ACS authentication page, for more details refer to 3D Secure Authentication
Gateway URL
Environment | Gateway url |
---|---|
Sandbox | https://payment.sandbox.mafpayments.com/api |
Production | https://payment.mafpayments.com/api |
Note: The sandbox API is available for integration and compatibility testing of new features before having available on the production environment.
Authentication
This API uses basic authentication and merchant identifier to authenticate the requests, basic authentication value must be passed in the Authorization header parameter and the merchant identifier value must be passed in Merchant-Id header parameter. MAF Pay will provide the credentials required for both parameters.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
Merchant-Id: YourTestingMID
Transaction Request
Note: The request content-type should be set to application/x-www-form-urlencoded.
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “pay”, for authorization the command will hold the value “authorize”. | None | Yes | 30 | A |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | - , . ,_ | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | - , . ,_ | Yes | 70 | AN |
cardToken | The card alias name, that has been assigned to a specific user card. | None | Yes | 30 | AN |
securityCode | Card security code. | * | No | 4 | N |
amount | A positive integer representing the transaction amount. | None | Yes | 9 | N |
currency | ISO 3166 Alpha-3 code | None | Yes | 3 | A |
eci | The ecommerce indicator of this transaction. This parameter will hold the value moto or recurring. | None | Yes | 10 | A |
category | A value representing the category you will use to override the default category of store if required. In order to activate this feature please contact MAF Pay team and agree on the categories and setup if needed. | None | No | 20 | AN |
customerEmail | The customer email address. | - , . ,_ ,@ | No | 100 | AN |
customerIp | Customer IP address. | . | No | 50 | N |
customerPhone | The customer phone number. | + | No | 16 | N |
description | A text that used by merchants to describe the transaction. | Space | No | 200 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
returnUrl | Represents the merchant URL which we will use to redirect the customer to the merchant website. You can use this parameter to override the value on your store integration settings. | : , / , . , \ , - , _ | No | 700 | AN |
redeemAmount | A positive integer representing the rewards redeem amount. | None | No | 9 | N |
memberId | The loyalty program membership ID of the user. | None | No | 50 | AN |
program | The supported loyalty program that will be used in the earn and redeem process, possible values are: share. | None | No | 5 | A |
locationId | The store location ID which was generated by the loyalty program. | None | No | 70 | AN |
sponsorId | The store sponsor ID which was generated by the loyalty program. | None | No | 70 | N |
recurringIntent | The initial transaction must be identified as recurringIntent to process recurring transactions using the cardToken. The first transaction must be eCommerce with recurringIntent=yes. The parameter has two possible values 'yes'/'no', and the default value is 'no'. | None | No | 10 | A |
Note: In order for merchants to process recurring transactions against the already stored card, you have to process the first 'pay'/'authorize' transaction as an eCommerce transaction if this card is not already 3DS verified with recurringIntent
parameter.
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “pay”, for authorization the command will hold the value “authorize”. | 30 | A |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
gatewayId | A unique reference for the transaction generated by the gateway. | 30 | AN |
cardToken | The card alias name, that has been assigned to a specific card details. | 30 | AN |
amount | A positive integer representing the transaction amount. | 9 | N |
currency | Three-letter ISO currency code | 3 | A |
eci | The ecommerce indicator of this transaction. This parameter will hold the value moto or recurring. | 10 | A |
category | A value representing the category you will use to override the default category of store if required. In order to activate this feature please contact MAF Pay team and agree on the categories and setup if needed. | 20 | AN |
customerEmail | The customer email address. | 100 | AN |
customerIp | Customer IP address. | 50 | N |
customerPhone | The customer phone number. | 16 | N |
description | A text that used by merchants to describe the transaction. | 200 | AN |
authCode | Identifier for this transaction. | 10 | AN |
threeDsUrl | This is the URL that will redirect the payer to the card issuer's ACS server. This parameter will be returned only with 3D Secure 1 configuration. |
70 | AN |
threeDsAuthId | A unique reference for the 3D Secure authentication generated by the gateway, this parameter used to complete the 3D Secure 2 authentication. This parameter will be returned only with 3D Secure 2 configuration. |
70 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | 200 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
returnUrl | Represents the merchant URL which we will use to redirect the customer to the merchant website. You can use this parameter to override the value on your store integration settings. | 700 | AN |
redeemAmount | A positive integer representing the rewards redeem amount. | 9 | N |
memberId | The loyalty program membership ID of the user. | 50 | AN |
program | The supported loyalty program that will be used in the earn and redeem process, possible values are: share. | 5 | A |
locationId | The store location ID which was generated by the loyalty program. | 70 | AN |
sponsorId | The store sponsor ID which was generated by the loyalty program. | 70 | N |
pointsEarned | The reward points earned. | 70 | N |
pointsRedeemed | The reward points redeemed. | 70 | N |
cardIssuer | The name of the bank that has issued the card. Note this parameter will not be part of the default response. To receive this parameter, please raise a request. |
60 | AN |
cardBin | The bank identification number (BIN) is the initial six numbers that appear on the card. Note this parameter will not be part of the response by default. To activate this parameter, please raise a request. |
6 | N |
cardIssuerCountry | The country of the bank that has issued the card. Note this parameter will not be part of the default response. To receive this parameter, please raise a request. |
60 | AN |
You will receive pay/authorize response on your transaction feedback URL configured on your merchant account. It is highly advised that you rely this server-to-server feedback to confirm the payment status as the pay/authorize requests are prone to redirection interruption issues. please refer to Server Notification System for more details
Apple Pay
Apple Pay is a mobile and online purchasing experience for customers with supported iOS and macOS devices.
Accept Apple Pay payments using our APIs, and build your own payment form to have full control over the look and feel of your checkout page.
Setup Apple Pay
Before you start, you’ll need to be enrolled in the Apple Developer Program and set up MAF Pay on your server and in your app. Next, follow these steps:
Create Payment certificate
- Set up the Apple Merchant ID using your Apple developer account, we recommend to add a prefix “merchant.com.mafpay” to your Apple Merchant ID. Note: For test accounts, we recommend adding .sandbox to the identifier, for example: merchant.com.mafpay. <merchantAccount> .sandbox
- Send your Apple Merchant ID to MAF Pay integration support team, so they can provide you with a CSR file.
- Create a new Payment Processing Certificate using your Apple developer account and the CSR file received from MAF Pay integration support team.
- Send the Apple Merchant ID and Payment Processing Certificate to MAF Pay integration support team.
- Wait until our integration support team confirms that the certificate is activated.
Integrate Apple Pay with your App
Apple Pay is available to you through the following channels:
- MAF Pay iOS SDK: please refer to iOS SDK for more details.
- Apple Pay PassKit: please refer to Apple Pay Passkit for more details.
- Apple Pay web SDK: please refer to Apple Pay web SDK for more details.
Payment request
To process a payment using Apple Pay Payment Token, you can include the encrypted Apple Pay Payment Token details to MAF Pay payment requests (Pay and Authorize).
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “pay”, for authorization the command will hold the value “authorize”. | None | Yes | 30 | A |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | - , . ,_ | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | - , . ,_ | Yes | 70 | AN |
walletIndicator | This parameter holds the value that indicates the wallet used to process this transaction, for Apple Pay the value is “applePay” | None | Yes | 15 | A |
walletData | Encrypted payment data. Base64 encoded as a string. | + , / , = | Yes | 500 | AN |
walletHeader | Additional version-dependent information used to decrypt and verify the payment. | Space , ! , " , # , $ , % , & , ' , ( , ) , * | Yes | 3000 | AN |
walletSignature | Signature of the payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm. | + , / , = | Yes | 3000 | AN |
walletVersion | Version information about the payment token. The token uses EC_v1 for ECC-encrypted data, and RSA_v1 for RSA-encrypted data. | _ | Yes | 20 | AN |
amount | A positive integer representing the transaction amount. | None | Yes | 9 | N |
currency | ISO 3166 Alpha-3 code | None | Yes | 3 | A |
eci | The ecommerce indicator of this transaction. This parameter will hold the value "ecommerce". | None | Yes | 10 | A |
category | A value representing the category you will use to override the default category of store if required. In order to activate this feature please contact MAF Pay team and agree on the categories and setup if needed. | None | No | 20 | AN |
customerEmail | The customer email address. | - , . ,_ ,@ | No | 100 | AN |
customerIp | Customer IP address. | . | No | 50 | N |
customerPhone | The customer phone number. | + | No | 16 | N |
description | A text that used by merchants to describe the transaction. | Space | No | 200 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
Payment response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “pay”, for authorization the command will hold the value “authorize”. | 30 | A |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
gatewayId | A unique reference for the transaction generated by the gateway | 30 | AN |
walletIndicator | This parameter holds the value that indicates the wallet used to process this transaction, for Apple Pay the value is "applePay" | 15 | A |
amount | A positive integer representing the transaction amount. | 9 | N |
currency | Three-letter ISO currency code | 3 | A |
eci | The ecommerce indicator of this transaction. This parameter will hold the value "ecommerce". | 10 | A |
category | A value representing the category you will use to override the default category of store if required. In order to activate this feature please contact MAF Pay team and agree on the categories and setup if needed. | 20 | AN |
customerEmail | The customer email address. | 100 | AN |
customerIp | Customer IP address. | 50 | N |
customerPhone | The customer phone number. | 16 | N |
description | A text that used by merchants to describe the transaction. | 200 | AN |
authCode | Identifier for this transaction. | 10 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | 200 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
cardIssuer | The name of the bank that has issued the card. Note this parameter will not be part of the default response. To receive this parameter, please raise a request. |
60 | AN |
cardBin | The bank identification number (BIN) is the initial six numbers that appear on the card. Note this parameter will not be part of the response by default. To activate this parameter, please raise a request. |
6 | N |
cardIssuerCountry | The country of the bank that has issued the card. Note this parameter will not be part of the default response. To receive this parameter, please raise a request. |
60 | AN |
Samsung Pay
Samsung Pay is a mobile and online purchasing experience for customers with supported Android devices.
Accept Samsung Pay payments using our APIs, and build your own payment form to have full control over the look and feel of your checkout page.
Setup Samsung Pay
Before you start, you’ll need to be enrolled in the Samsung Pay Program and set up MAF Pay on your server and in your app. Next, follow these steps:
- Request for a CSR from MAF Pay which is needed for data encryption with the Samsung Pay system.
- Create your Samsung Pay developer account by signing up in Samsung Pay website.
- In your Samsung Pay developer account, go to My Projects and create a service and an app.
- Choose MAF Pay as your Payment Gateway, and upload the CSR file that you received from us.
Integrate Samsung Pay with your Web/App
Samsung Pay is available to you through the following channels:
- Integrate with Samsung Pay SDK for web and App by following Samsung Pay Guide and map the fields between Samsung Pay and MAF Pay.
Payment request
To process a payment using Samsung Pay Payment data, you can include the encrypted Samsung Pay Payment data details to MAF Pay payment requests (Pay and Authorize).
Note: The request content-type should be set to application/json.
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “pay”, for authorization the command will hold the value “authorize”. | None | Yes | 30 | A |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | - , . ,_ | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | - , . ,_ | Yes | 70 | AN |
walletIndicator | This parameter holds the value that indicates the wallet used to process this transaction, for Samsung Pay the value is “samsungPay” | None | Yes | 15 | A |
walletData | Encrypted payment data. Base64 encoded as a string. | + , / , = | Yes | 500 | AN |
amount | A positive integer representing the transaction amount. | None | Yes | 9 | N |
currency | ISO 3166 Alpha-3 code | None | Yes | 3 | A |
eci | The ecommerce indicator of this transaction. This parameter will hold the value "ecommerce". | None | Yes | 10 | A |
category | A value representing the category you will use to override the default category of store if required. In order to activate this feature please contact MAF Pay team and agree on the categories and setup if needed. | None | No | 20 | AN |
customerEmail | The customer email address. | - , . ,_ ,@ | No | 100 | AN |
customerIp | Customer IP address. | . | No | 50 | N |
customerPhone | The customer phone number. | + | No | 16 | N |
description | A text that used by merchants to describe the transaction. | Space | No | 200 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
Payment response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “pay”, for authorization the command will hold the value “authorize”. | 30 | A |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
gatewayId | A unique reference for the transaction generated by the gateway | 30 | AN |
walletIndicator | This parameter holds the value that indicates the wallet used to process this transaction, for Samsung Pay the value is "samsungPay" | 15 | A |
amount | A positive integer representing the transaction amount. | 9 | N |
currency | Three-letter ISO currency code | 3 | A |
eci | The ecommerce indicator of this transaction. This parameter will hold the value "ecommerce". | 10 | A |
category | A value representing the category you will use to override the default category of store if required. In order to activate this feature please contact MAF Pay team and agree on the categories and setup if needed. | 20 | AN |
customerEmail | The customer email address. | 100 | AN |
customerIp | Customer IP address. | 50 | N |
customerPhone | The customer phone number. | 16 | N |
description | A text that used by merchants to describe the transaction. | 200 | AN |
authCode | Identifier for this transaction. | 10 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | 200 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
cardIssuer | The name of the bank that has issued the card. Note this parameter will not be part of the default response. To receive this parameter, please raise a request. |
60 | AN |
cardBin | The bank identification number (BIN) is the initial six numbers that appear on the card. Note this parameter will not be part of the response by default. To activate this parameter, please raise a request. |
6 | N |
cardIssuerCountry | The country of the bank that has issued the card. Note this parameter will not be part of the default response. To receive this parameter, please raise a request. |
60 | AN |
Google Pay
Google Pay is a mobile and online purchasing experience for customers with supported mobile devices.
Accept Google Pay payments using our APIs, and build your own payment form to have full control over the look and feel of your checkout page.
Integrate Google Pay with your Web/App
Google Pay is available to you through the following channels:
- MAF Pay web library: Please refer to Web Library for more details.
- MAF Pay Android SDK: please refer to Android SDK for more details.
- Google Pay direct Integration: Please refer to Direct Integration for more details.
Direct Integration
Setup Google Pay
Before you start, you will need to be enrolled in the Google Pay Program and set up MAF Pay on your server. Next, follow these steps:
- Contact MAF Pay integration support team to enable Google Pay on your account and they will provide you with gateway and gatewayMerchantId required in your integration with Google pay.
- Integrate with Google Pay to acquire the Payment Token, please refer to the Google Pay for Payment for more details.
- After receiving the Payment Token, you need to encode it using Base64 encoding and pass the value with MAF Pay payment request.
- For going live, you need to make sure you request a merchant ID from the Google Pay Business Console.
Example 1 - Google Pay Token
{"signature":"MEUCIQDhTxhHqwY8pXB9hpYxaSK5jFgsqpG2E1rX
77QXssK8tAIgUBvYYAI/bnBS8T/Tfxnm2AF981Mv5y0pHyGexM5dMJk\u003d","pr
otocolVersion":"ECv1","signedMessage":"{\"encryptedMessage\":\"ody
UGGA7B+blletYcJbS43AQUFQJpWEFCN4UuUExQ5LX0\/XcLwKElXcB95nMnmPO9lM2
KGp13FYsL768ccCzAjBGLYF+fugcJTcvkrUhcNSyXr7hwf12BEsrweqJM6I7Vs5lfr
PAukRJeLDQG4FxmTLW49QyP8vIZC+tz2c+Z3zozzI5oB9jE8fA2dolFa13Cu6gXqdK
H\/IHRh7UniLUuTy+0G5FQV2pwST2uBSNNkZhb8WYJDHbxBjz0UebVP+ObmT5cc8AK
U5dgHRdfr4GKpEZ4EBzB90BPxLqYHpopriJ6lbFgFVsQQ6\/8HBqQ7ImIMH5y7G8p8
qAFkWnB78ZcL0Fh5BjXojkxGoFp2gjAsrhhttHAFbe3WQBuPkwJu09\/6\/MyJpCSr
pMHFouF\/dj0SYjQ+xI097lCHZec7jQrAhISLWZ9DZkuMvGKPWpu0CKn2XqTXQ=\",
\"ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEnn4yj
y0N6xlXO8\/8j7\/4jvmLJCYAqgXLwP1FhjuTgIM9oCtPijZfI9so2QEOs2ZnVp3D0
dl3JYIDVe+396KkAQ==\",\"tag\":\"DRpcc+YQ33RNgsTcxztnJbMJnirbU5DW3d
StjfhFiwc=\"}"}
Example 2 - Base 64 encoded payment token
eyJzaWduYXR1cmUiOiJNRVVDSVFEaFR4aEhxd1k4cFhCOWhwWXhhU0
s1akZnc3FwRzJFMXJYNzdRWHNzSzh0QUlnVUJ2WVlBSS9ibkJTOFQvVGZ4bm0yQUY5
ODFNdjV5MHBIeUdleE01ZE1Ka1x1MDAzZCIsInByb3RvY29sVmVyc2lvbiI6IkVDdj
EiLCJzaWduZWRNZXNzYWdlIjoie1wiZW5jcnlwdGVkTWVzc2FnZVwiOlwib2R5VUdH
QTdCK2JsbGV0WWNKYlM0M0FRVUZRSnBXRUZDTjRVdVVFeFE1TFgwXC9YY0x3S0VsWG
NCOTVuTW5tUE85bE0yS0dwMTNGWXNMNzY4Y2NDekFqQkdMWUYrZnVnY0pUY3ZrclVo
Y05TeVhyN2h3ZjEyQkVzcndlcUpNNkk3VnM1bGZyUEF1a1JKZUxEUUc0RnhtVExXND
lReVA4dklaQyt0ejJjK1ozem96ekk1b0I5akU4ZkEyZG9sRmExM0N1NmdYcWRLSFwv
SUhSaDdVbmlMVXVUeSswRzVGUVYycHdTVDJ1QlNOTmtaaGI4V1lKREhieEJqejBVZW
JWUCtPYm1UNWNjOEFLVTVkZ0hSZGZyNEdLcEVaNEVCekI5MEJQeExxWUhwb3ByaUo2
bGJGZ0ZWc1FRNlwvOEhCcVE3SW1JTUg1eTdHOHA4cUFGa1duQjc4WmNMMEZoNUJqWG
9qa3hHb0ZwMmdqQXNyaGh0dEhBRmJlM1dRQnVQa3dKdTA5XC82XC9NeUpwQ1NycE1I
Rm91RlwvZGowU1lqUSt4STA5N2xDSFplYzdqUXJBaElTTFdaOURaa3VNdkdLUFdwdT
BDS24yWHFUWFE9XCIsXCJlcGhlbWVyYWxQdWJsaWNLZXlcIjpcIk1Ga3dFd1lIS29a
SXpqMENBUVlJS29aSXpqMERBUWNEUWdBRW5uNHlqeTBONnhsWE84XC84ajdcLzRqdm
1MSkNZQXFnWEx3UDFGaGp1VGdJTTlvQ3RQaWpaZkk5c28yUUVPczJablZwM0QwZGwz
SllJRFZlKzM5NktrQVE9PVwiLFwidGFnXCI6XCJEUnBjYytZUTMzUk5nc1RjeHp0bk
piTUpuaXJiVTVEVzNkU3RqZmhGaXdjPVwifSJ9
Payment Request
To process a payment using Google Pay Payment data, you can include the encrypted Google Pay Payment data details to MAF Pay payment requests (Pay and Authorize).
Note: The request content-type should be set to application/json.
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “pay”, for authorization the command will hold the value “authorize”. | None | Yes | 30 | A |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | None | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | None | Yes | 70 | AN |
walletIndicator | This parameter holds the value that indicates the wallet used to process this transaction, for Google Pay the value is “googlePay” | None | Yes | 15 | A |
walletData | Encrypted payment data. Base64 encoded as a string. | + , / , = | Yes | 500 | AN |
amount | A positive integer representing the transaction amount. | None | Yes | 9 | N |
currency | ISO 3166 Alpha-3 code | None | Yes | 3 | A |
eci | The ecommerce indicator of this transaction. This parameter will hold the value "ecommerce". | None | Yes | 10 | A |
category | A value representing the category you will use to override the default category of store if required. In order to activate this feature please contact MAF Pay team and agree on the categories and setup if needed. | None | No | 20 | AN |
customerEmail | The customer email address. | - , . ,_ ,@ | No | 100 | AN |
customerIp | Customer IP address. | . | No | 50 | N |
customerPhone | The customer phone number. | + | No | 16 | N |
description | A text that used by merchants to describe the transaction. | Space | No | 200 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
Payment response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “pay”, for authorization the command will hold the value “authorize”. | 30 | A |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
gatewayId | A unique reference for the transaction generated by the gateway | 30 | AN |
walletIndicator | This parameter holds the value that indicates the wallet used to process this transaction, for Samsung Pay the value is "samsungPay" | 15 | A |
amount | A positive integer representing the transaction amount. | 9 | N |
currency | Three-letter ISO currency code | 3 | A |
eci | The ecommerce indicator of this transaction. This parameter will hold the value "ecommerce". | 10 | A |
category | A value representing the category you will use to override the default category of store if required. In order to activate this feature please contact MAF Pay team and agree on the categories and setup if needed. | 20 | AN |
customerEmail | The customer email address. | 100 | AN |
customerIp | Customer IP address. | 50 | N |
customerPhone | The customer phone number. | 16 | N |
description | A text that used by merchants to describe the transaction. | 200 | AN |
authCode | Identifier for this transaction. | 10 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | 200 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
paymentOption | The selected payment option, in case of Google Pay the parameter will hold the card brand used, for example - "visa", "mastercard", "amex" . | 30 | AN |
cardIssuer | The name of the bank that has issued the card. Note this parameter will not be part of the default response. To receive this parameter, please raise a request. |
60 | AN |
cardBin | The bank identification number (BIN) is the initial six numbers that appear on the card. Note this parameter will not be part of the response by default. To activate this parameter, please raise a request. |
6 | N |
cardIssuerCountry | The country of the bank that has issued the card. Note this parameter will not be part of the default response. To receive this parameter, please raise a request. |
60 | AN |
Buy Now Pay Later
In order to enable Buy Now Pay Later (BNPL) payment option on your checkout page, MAF Pay have consolidated all BNPL providers under one umbrella which allows you to integrate once and offer all the BNPL provides to your customers.
Transaction Flow
- Using MAF Pay mobile SDKs and web library the merchant places the BNPL UI component and apply the required customization.
- The merchant sends a server-to-server request to create checkout session to acquire new checkout session token.
- The merchant passes the checkout session token created to the checkout function in the mobile SDKs and web library.
- MAF Pay will display the available BNPL providers in the checkout session and handle the payment flow once the customers selects one.
- MAF Pay will respond to one of the callbacks functions and sends a server-to-server feedback to the merchant API.
For more technical details regarding Web Library refer to Web Library.
For more technical details regarding MAF Pay SDKs refer to iOS SDK or Android SDK.
Checkout Session
This API creates a checkout session token that is used to render all BNPL providers on the merchant checkout page.
Gateway URL
Environment | URL |
---|---|
Sandbox | https://payment.sandbox.mafpayments.com/api |
Production | https://payment.mafpayments.com/api |
Note: The sandbox API is available for integration and compatibility testing of new features before having available on the production environment.
Authentication
This API uses basic authentication and merchant identifier to authenticate the requests, basic authentication value must be passed in the Authorization header parameter and the merchant identifier value must be passed in Merchant-Id header parameter. MAF Pay will provide the credentials required for both parameters.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
Merchant-Id: YourTestingMID
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of create checkout session the command will hold the value "checkoutSession". | None | Yes | 30 | A |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | - , . ,_ | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | - , . ,_ | Yes | 70 | AN |
amount | A positive integer representing the transaction amount. | None | Yes | 9 | N |
currency | ISO 3166 Alpha-3 code. | None | Yes | 3 | A |
paymentOperation | The required payment operation to be applied on this checkout session, This parameter will hold the value pay or authorize. | None | No | 30 | A |
checkoutOptions | The checkout option(s) to be rendered to the customer, . This parameter will hold a list of the possible values: 1.bnpl 2.spotii 3.tabby 4.tamara 5.applePay 6.googlePay |
Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | A |
restrictCheckoutOptions | The checkout option(s) to be hidden from the customer. This parameter will hold a list of the possible values: 1.bnpl 2.spotii 3.tabby 4.tamara 5.applePay 6.googlePay |
None | No | 15 | A |
eci | The ecommerce indicator of this transaction. This parameter will hold the value ecommerce | None | No | 3 | A |
customerEmail | The customer email address. | - , . , _ , @ | Yes | 250 | AN |
customerIp | Customer IP address. | . | Yes | 16 | N |
customerPhone | The customer phone number. | + | Yes | 16 | N |
customerName | The customer name. | -.<>“’ | No | 250 | N |
description | A text that used by merchants to describe the transaction. | Space | No | 200 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
language | User preferred language, possible values are: 1. en 2. ar |
None | No | 2 | A |
sku | The list of the items details that the customer selected. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | Yes | 5000 | AN |
sku.description | A description for the item | Space | Yes | 300 | AN |
sku.quantity | Quantity of the item selected by the customer. | None | Yes | 9 | N |
sku.itemId | The identifier of the item. | None | Yes | 20 | AN |
sku.title | The item title. | Space, | Yes | 300 | AN |
sku.unitPrice | The unit price of the item. | None | Yes | 9 | N |
billingAddress | The details of the customer billing address. | None | No | 400 | AN |
billingAddress.title | The title of the billing address. | None | No | 5 | AN |
billingAddress.first_name | Customer first name. | -.<>“’ | No | 50 | AN |
billingAddress.last_name | Customer family name. | -.<>“’ | No | 50 | AN |
billingAddress.line1 | The line 1 of the address. | Space # , | No | 46 | AN |
billingAddress.line2 | The line 2 of the address. | Space # , | No | 46 | AN |
billingAddress.line3 | The line 3 of the address. | Space # , | No | 46 | AN |
billingAddress.line4 | The line 4 of the address. | Space # , | No | 46 | AN |
billingAddress.state | The city of the billing address. | None | No | 50 | AN |
billingAddress.postcode | Postal code. | None | No | 10 | AN |
billingAddress.country | The address county. | None | No | 3 | AN |
billingAddress.phone | Customer phone number. | + | No | 16 | AN |
shippingAddress | The details of the customer billing address. | None | No | 400 | AN |
shippingAddress.title | The title of the shipping address. | None | No | 5 | AN |
shippingAddress.first_name | Customer first name. | -.<>“’ | No | 50 | AN |
shippingAddress.last_name | Customer family name. | -.<>“’ | No | 50 | AN |
shippingAddress.line1 | The line 1 of the address. | Space # , | No | 46 | AN |
shippingAddress.line2 | The line 2 of the address. | Space # , | No | 46 | AN |
shippingAddress.line3 | The line 3 of the address. | Space # , | No | 46 | AN |
shippingAddress.line4 | The line 4 of the address. | Space # , | No | 46 | AN |
shippingAddress.state | The city of the shipping address. | None | No | 50 | AN |
shippingAddress.postcode | Postal code. | None | No | 10 | AN |
shippingAddress.country | The address county. | None | No | 3 | AN |
shippingAddress.phone | Customer phone number. | + | No | 16 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of create checkout session the command will hold the value "checkoutSession". | 30 | A |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
amount | A positive integer representing the transaction amount. | 9 | N |
currency | ISO 3166 Alpha-3 code. | 3 | A |
paymentOperation | The required payment operation to be applied on this checkout session, This parameter will hold the value pay or authorize. | 30 | A |
checkoutOptions | The checkout option(s) to be rendered to the customer, . This parameter will hold a list of the possible values: 1.bnpl 2.spotii 3.tabby 4.tamara 5.applePay 6.googlePay |
30 | AN |
eci | The ecommerce indicator of this transaction. This parameter will hold the value ecommerce | 3 | A |
customerEmail | The customer email address. | 250 | AN |
customerIp | Customer IP address. | 16 | N |
customerPhone | The customer phone number. | 16 | N |
customerName | The customer name. | 250 | N |
description | A text that used by merchants to describe the transaction. | 200 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | 200 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
token | The checkout session token which is required to complete the payment | 100 | AN |
language | User preferred language, possible values are: 1. en 2. ar |
2 | A |
Pay@Terminal
This payment feature allows partners to accept mobile payments in stores that accept MAF Pay payments. After detecting the cashier the partner system can send the payment details to MAF Pay for processing.
Transaction flow
The steps below presents Pay@Terminal flow:
The cashier has the invoiced amount ready and sent to MAF Pay through integrated POS or one of MAF Pay terminals.
The user taps on the payment button.
Your app will detect the terminal beacon.
Your system initiate a new Pay@Terminal request that contains the payment details to MAF Pay API.
MAF Pay will process the payment request then it will send a server notification message that contain the final status of the payment request.
Note: For more details regarding MAF Pay SDKs refer to iOS SDK or Android SDK.
Gateway URL
Environment | URL |
---|---|
Sandbox | https://terminal.sandbox.mafpayments.com/api |
Production | https://terminal.mafpayments.com/api |
Note: The sandbox API is available for integration and compatibility testing of new features before having them on the production environment.
Authentication
This API uses Auth0 authentication and partner identifier to authenticate the requests, Auth0 authentication token value must be passed in the Authorization header parameter and the partner identifier value must be passed in Partner-Id header parameter. MAF Pay will provide the credentials required for both parameters.
Partner Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
Partner-Id: YourTestingMID
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of Pay@Terminal. the command will hold the value “payAtTerminal”. | None | Yes | 30 | A |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | None | Yes | 70 | AN |
terminalId | The terminal identifier assigned. | _ , - | Yes | 30 | AN |
cardToken | The token of the card that will be used in the transaction processing. | None | No | 30 | AN |
rewardAmount | A positive integer representing the transaction reward amount. | None | Yes | 9 | N |
currency | The ISO 3166 Alpha-3 code of the transaction currency. | None | Yes | 3 | A |
rewardOption | The payment preferences selected by the customer, possible values are:
|
None | No | 20 | A |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of Pay@Terminal. the command will hold the value “payAtTerminal”. | 30 | A |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | 70 | AN |
terminalId | The terminal identifier assigned. | 30 | AN |
cardToken | The token of the card that will be used in the transaction processing. | 30 | AN |
rewardAmount | A positive integer representing the transaction reward amount. | 9 | N |
rewardOption | The payment preferences selected by the customer, possible values are:
|
20 | A |
currency | The ISO 3166 Alpha-3 code of the transaction currency. | 3 | A |
amount | A positive integer representing the transaction amount. | 9 | N |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | 200 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
Bank Transfer
This payment method allows merchants to accept bank transfer payments for the services/goods they provide to their customers. Bank transfer payment method available using same integration you use in checkout session.
Transaction flow
The steps below presents bank transfer flow:
- Create account holder ID for your customer.
- Link account holder bank by creating bank token using MAF Pay link bank component.
- Use your verified bank token to process payment.
Note: In case you are using Auth0 token for authentication, you can skip the first step as we will manage the account holders creation using the token provided.
Link Bank
In order for your customer to be able to make payment using bank transfer, first they need to authorise their bank to transfer funds from their account to your account. Your bank account will be added as a 'Beneficiary'. For some banks, creating a beneficiary can have a cool-down period of up to 24 hours.
MAF Pay provides the following channels to do link bank operation:
- MAF Pay web library: Please refer to Web Library for more details.
- MAF Pay Android SDK: please refer to Android SDK for more details.
- MAF Pay IOS SDK: Please refer to IOS SDK for more details.
Get Account Holder Banks
This operation allows merchants to retrieve all banks related to specific accountHolder from MAF Pay. MAF Pay provides the following channels to get account holder banks:
- API integration.
- MAF Pay Android SDK: please refer to Android SDK for more details.
- MAF Pay IOS SDK: Please refer to IOS SDK for more details.
Gateway URL
Environment | Gateway url |
---|---|
Sandbox | https://payment.sandbox.mafpayments.com/api |
Production | https://payment.mafpayments.com/api |
Note: The sandbox environment is available for integration and compatibility testing of new features before having them available on the production.
Authentication
This API uses basic authentication or Auth0 token along with the merchant identifier to authenticate the requests.
Basic authentication value or the Auth0 authentication token value must be passed in the Authorization header parameter.
Partner or merchant identifiers value must be passed in Partner-Id/Merchant-Id header parameter. MAF Pay provides the credentials required for both parameters.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
Merchant-Id: YourTestingPID
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlFrVk…
Merchant-Id: YourTestingMID
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of add account holder the command will hold the value “getAccountHolderBanks”. | None | Yes | 30 | A |
accountHolderId | The account holder ID that been created for the customer. | _ | No | 25 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of add account holder the command will hold the value “getAccountHolderTokens”. | 30 | A |
banks | A list of all banks details related to the accountHolderId. | 8000 | AN |
banks.bankToken | The banks alias name, that has been assigned to a specific user bank | 20 | N |
banks.status | This bank token status (i.e., VERIFIED) | 20 | A |
banks.bankName | The bank name. | 100 | N |
banks.bankCountry | The bank country. | 100 | N |
banks.bankLogo | The bank logo. | 500 | N |
responseCode | A code represents the result of the request processing. | 3 | N |
responseMessage | A text that describes the result of the request processing. | 100 | AN |
Payment
In this step, the customer will confirm the amount they want to transfer from their account to your account. MAF Pay provides bank transfer payment through checkout session component. Once payment initiation has been completed, you will receive the final payment status on your feedback URL configured on MAF Pay portal.
MAF Pay provides the following channels to integrate bank transfer payment:
- MAF Pay web library: Please refer to Web Library for more details.
- MAF Pay Android SDK: please refer to Android SDK for more details.
- MAF Pay IOS SDK: Please refer to IOS SDK for more details.
Note: You will need to generate checkout token before using MAF Pay components, please follow checkout session guide to generate the checkout token. Note: Bank transfer payments only possible using verified linked banks
Payment Link
Payment link is an online purchasing experience for customers allows you to generate your invoice details with a customized payment options, and send it to your customers directly.
Create Payment links using our APIs, and fill your own invoice items to send it to your customers without having to create your own checkout page.
Setup Payment Link
Before you start using Payment link APIs, you’ll need to activate Payment Link service for your store through MAF portal. Then, configure the bellow invoice settings:
- Upload your logo
- Invoice title
- Merchant address
- Phone Number
Then configure your own invoice template.
Create Payment Link
This API generate a payment link with your customized invoice settings and template.
Gateway URL
Environment | URL |
---|---|
Sandbox | https://payment.sandbox.mafpayments.com/api |
Production | https://payment.mafpayments.com/api |
Note: The sandbox API is available for integration and compatibility testing of new features before having available on the production environment.
Authentication
This API uses basic authentication and merchant identifier to authenticate the requests, basic authentication value must be passed in the Authorization header parameter and the merchant identifier value must be passed in Merchant-Id header parameter. MAF Pay will provide the credentials required for both parameters.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
Merchant-Id: YourTestingMID
Create Payment Link Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of create payment link the command will hold the value "createPaymentLink". | None | Yes | 30 | A |
invoiceNumber | The identifier for the invoice. The merchant is responsible for generating this reference. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | Yes | 70 | AN |
dueDate | Invoice date for payment link. | ‐ | Yes | 70 | AN |
expiryDate | The expiry date for the payment link. | ‐ | Yes | 9 | AN |
customerName | The customer name. | -.<>“’ | Yes | 250 | AN |
customerEmail | The customer email address. | - , . , _ , @ | Yes | 250 | AN |
customerAddress | The customer physical address. | - , . , _ , @ | Yes | 250 | AN |
customerPhone | The customer phone number. | + | No | 16 | N |
paymentMethod | The required payment option to be applied on this payment link. This parameter will hold a list of the possible values: 1.creditAndDebitCards 2.applePay 3.tabby 4.tamara |
None | No | 30 | A |
paymentLinkId | The unique indentifier for the payment link. The merchant can generate this reference or MAF pay will generate it for him. | None | No | 150 | AN |
currency | Payment link invoice currency. | None | Yes | 3 | A |
sku | The list of the items details that the customer selected. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | Yes | 5000 | AN |
sku.description | A description for the item. | Space | Yes | 300 | AN |
sku.quantity | Quantity of the item selected by the customer. | None | Yes | 5 | N |
sku.unitPrice | The unit price of the item. | None | Yes | 9 | N |
sku.totalAmount | The SKU total amount, this attribute to be sent only with "calculation": "no" | None | No | 9 | N |
shippingAmount | If shipping is enabled, this is shipping amount to be added to the total invoice. | None | No | 9 | N |
notes | Optional notes for merchant's customer. | None | No | 250 | AN |
termsAndConditions | Optional notes for merchant's customer. | None | No | 250 | AN |
calculation | Optional request attribute to enable/disable total and sku items calculations. Possible values: "yes" or "no", default will be "yes". | None | No | 3 | A |
total | The total amount, this attribute to be sent only with "calculation": "no" | None | No | 9 | N |
subtotal | The subtotal amount, this attribute to be sent only with "calculation": "no" | None | No | 9 | N |
vat | The VAT amount, this attribute to be sent only with "calculation": "no" | None | No | 9 | N |
createEmail | send email to customers when the payment link created or updated, will hold the value "yes" or "no", default will be "no" | None | No | 10 | A |
confirmationEmail | send email to customers when pay the payment link, will hold the value "yes" or "no", default will be "no" | None | No | 10 | A |
Create Payment Link Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of create payment link the command will hold the value "createPaymentLink". | 30 | A |
invoiceNumber | The identifier for the invoice. The merchant is responsible for generating this reference. | 40 | AN |
dueDate | Invoice date for payment link. | 70 | AN |
paymentLink | The payment link URL : https://x.x.mafpayments.com/route/payment-link?id=xxxx | 70 | AN |
expiryDate | The expiry date for the payment link. | 9 | N |
paymentLinkId | The unique indentifier for the payment link. The merchant can generate this reference or MAF pay will generate it automatically. | 70 | AN |
sku | The list of the items details that the customer selected. | 5000 | AN |
sku.description | A description for the item. | 300 | AN |
sku.quantity | Quantity of the item selected by the customer. | 9 | N |
sku.unitPrice | The unit price of the item. | 9 | N |
total | Total calculated amount. | 9 | N |
vat | VAT amount calculated as defined payment link settings. | 9 | N |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
Cancel Payment Link
Use this API to cancel an existing payment link.
Environment | URL |
---|---|
Sandbox | https://payment.sandbox.mafpayments.com/api |
Production | https://payment.mafpayments.com/api |
Note: The sandbox API is available for integration and compatibility testing of new features before having available on the production environment.
Authentication
This API uses basic authentication and merchant identifier to authenticate the requests, basic authentication value must be passed in the Authorization header parameter and the merchant identifier value must be passed in Merchant-Id header parameter. MAF Pay will provide the credentials required for both parameters.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
Merchant-Id: YourTestingMID
Cancel Payment Link Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of cancel payment link the command will hold the value "cancelPaymentLink". | None | Yes | 30 | A |
paymentLinkId | The unique indentifier for the payment link. | None | Yes | 150 | AN |
Cancel Payment Link Response
Parameter Name | Description | Length | Type |
---|---|---|---|
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
paymentLinkId | The unique indentifier for the payment link. | 150 | AN |
Services
Tokenization
The tokenization service allows the merchant to store the customer’s sensitive data in MAF Pay’s secure and PCI compliant system and replace this data with a unique token that refers to the stored data.
Transaction flow
- The merchant creates the form that collects the cardholder sensitive data and assigns the form submission to MAF Pay tokenization URL.
- The user enters the cardholder data and clicks on the submission “pay” button.
- The form submits the tokenization request to MAF Pay Services.
- MAF Pay creates a token for the sensitive data and sends it back to the merchant via tokenization response.
Integration Methods
In order to securely create the payment page MAF Pay provides the following methods:
Direct POST
In this method you can create the whole payment page and pointing the submission of the form to our Payment APIs
Gateway URL
Environment | Gateway url |
---|---|
Sandbox | https://payment.sandbox.mafpayments.com/tokenize |
Production | https://payment.mafpayments.com/tokenize |
Note: The sandbox environment is available for integration and compatibility testing of new features before having them available on the production.
Authentication
This API supports two types of authentication mechanisms API Keys and Auth0 tokens, depending on the integration setup MAF Pay will provide you with the account credentials necessary to simulate test tokenization requests.
- API Key: You need to pass the value of your API key in the apiKey parameter.
- Auth0: You need to pass the authentication token value in the authorization header parameter.
Transaction Request
Note: The request content-type should be set to application/x-www-form-urlencoded.
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
apiKey | A unique identifier that is used to authenticate requests associated with your account. | _ | Yes | 70 | AN |
merchantId | The unique identifier assigned for the merchant account. | - | Yes | 50 | AN |
command | The operation name requested, in case of Pay the command will hold the value "tokenize". | None | Yes | 30 | A |
cardNumber | The card number of the payer. | * | Yes | 18 | N |
expiryMonth | The card expiry month. | None | Yes | 2 | N |
expiryYear | The card expiry year. | None | Yes | 2 | N |
cardHolderName | The name on the card. | Space | No | 30 | AN |
verifyCard | An indicator that is used to specify the type of verification that should be applied on the payment card, possible values are:threeds: The card issuer 3Ds verification.auth: Random amount deduction. | None | No | 10 | A |
rememberCard | An indicator that you can use to give customers the ability to decide whether or not they want to save their cards, possible values are: "yes" and "no", and by default, the option is yes. Please note that you cannot send "rememberCard": "no" with "verifyCard" parameter since there is no value in verifying the card without saving it. | None | No | 10 | A |
securityCode | The card security code, also known as CVC and CVV. | * | No | 4 | N |
accountHolderId | The account holder ID that the card token will be linked to. | _ | No | 30 | AN |
defaultCard | An indicator that you can use to set the card as default, possible values are: "yes" and "no". By default the option is no. | None | No | 3 | A |
extraData1 | Can be used to attach specific value to this transaction, this parameter will always return in the response. | Space,!,#,$,%,(,),*,+,,,-,.,:,;,=,?,@,_ | No | 100 | AN |
extraData2 | Can be used to attach specific value to this transaction, this parameter will always return in the response. | Space,!,#,$,%,(,),*,+,,,-,.,:,;,=,?,@,_ | No | 100 | AN |
extraData3 | Can be used to attach specific value to this transaction, this parameter will always return in the response. | Space,!,#,$,%,(,),*,+,,,-,.,:,;,=,?,@,_ | No | 100 | AN |
returnUrl | Represents the merchant URL which we will use to redirect the customer to the merchant website. You can use this parameter to override the value on your store integration settings. | : , / , . , \ , - , _ | No | 700 | AN |
recurringIntent | The initial transaction must be identified as recurringIntent to process recurring transactions with the resulted token. The parameter has two possible values 'yes'/'no', and the default value is 'no'. | None | No | 10 | A |
Note: In order for merchants to process recurring transactions while tokenizing the card , you have to send verifyCard=3ds along with recurringIntent=yes parameters
Tokenization Response
Parameter Name | Description | Length | Type |
---|---|---|---|
apiKey | A unique identifier that is used to authenticate requests associated with your account. | 70 | AN |
merchantId | The unique identifier assigned for the merchant account. | 50 | AN |
command | The operation name requested, in case of Pay the command will hold the value “tokenize”. | 30 | A |
cardMaskedNumber | The masked card number of the payer. | 18 | N |
expiryMonth | The card expiry month. | 2 | N |
expiryYear | The card expiry year. | 2 | N |
cardHolderName | The name on the card. | 30 | AN |
cardType | The classification of the payer payment card (i.e., Credit, Debit). | 10 | A |
cardBrand | The respective financial institutions (i.e., AMEX, VISA, MasterCard, Discover & JCB). | 15 | A |
cardBin | The bank identification number (BIN) is the initial four to six numbers that appear on a credit card. | 6 | N |
cardToken | The card alias name, that has been assigned to a specific user card. | 30 | AN |
extraData1 | Can be used to attach specific value to this transaction, this parameter will always return in the response. | 100 | AN |
extraData2 | Can be used to attach specific value to this transaction, this parameter will always return in the response. | 100 | AN |
extraData3 | Can be used to attach specific value to this transaction, this parameter will always return in the response. | 100 | AN |
accountHolderId | The account holder ID that the card token will be linked to. | 30 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
returnUrl | Represents the merchant URL which we will use to redirect the customer to the merchant website. You can use this parameter to override the value on your store integration settings. | 700 | AN |
Adding AccountHolder
The accountHolder service allows the merchant and partners to create wallets for their customer’s on MAF Pay secure and PCI compliant system, this wallet will hold all the payment instruments for a specific MAF customer.
Gateway URL
Environment | Gateway url |
---|---|
Sandbox | https://payment.sandbox.mafpayments.com/api |
Production | https://payment.mafpayments.com/api |
Note: The sandbox environment is available for integration and compatibility testing of new features before having them available on the production.
Authentication
This API uses basic authentication and merchant/partner identifier to authenticate the requests, basic authentication value must be passed in the Authorization header parameter and the merchant/partner identifier value must be passed in Merchant-Id/Partner-Id header parameter. MAF Pay will provide the credentials required for both parameters.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
PartnerId: YourTestingPID
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of add account holder the command will hold the value “addAccountHolder”. | None | Yes | 30 | A |
name | The full name of the customer. | -.<>“’ | Yes | 100 | AN |
The email of the customer. The format should be as follows: <email>@<domain> | - , . , _ , @ | Yes | 330 | AN | |
mobileNumber | The mobile number of the customer. The format should be one of the following: 1. + <country code> <mobile number> 2. 00 <country code> <mobile number> |
+ , | Yes | 20 | N |
memberId | The program membership ID of the user. | None | No | 50 | AN |
userId | The user ID in the authentication system. | | | No | 50 | AN |
description | A description or additional value to be linked to the customer wallet. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 1000 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of add account holder the command will hold the value “addAccountHolder”. | 30 | A |
name | The full name of the customer. | 100 | AN |
The email of the customer. The format should be as follows: <email>@<domain> | 330 | AN | |
mobileNumber | The mobile number of the customer. The format should be one of the following: 1. + <country code> <mobile number> 2. 00 <country code> <mobile number> |
20 | N |
accountHolderId | The accountHolder ID that been created for the customer. | 100 | AN |
memberId | The program membership ID of the user. | 50 | AN |
userId | The user ID in the authentication system. | 50 | AN |
description | A description or additional value to be linked to the customer wallet. | 1000 | AN |
responseCode | A code represents the result of the request processing. | 3 | N |
responseMessage | A text that describes the result of the request processing. | 100 | AN |
Get AccountHolder Tokens
The get accountholder tokens service allows the merchant and partners to retrieve all payment instruments related to specific accountHolder from MAF Pay.
Gateway URL
Environment | Gateway url |
---|---|
Sandbox | https://payment.sandbox.mafpayments.com/api |
Production | https://payment.mafpayments.com/api |
Note: The sandbox environment is available for integration and compatibility testing of new features before having them available on the production.
Authentication
This API uses basic authentication or Auth0 token along with the partner/merchant identifier to authenticate the requests.
Basic authentication value or the Auth0 authentication token value must be passed in the Authorization header parameter.
Partner or merchant identifiers value must be passed in Partner-Id/Merchant-Id header parameter. MAF Pay provides the credentials required for both parameters.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
PartnerId: YourTestingPID
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlFrVk…
Merchant-Id: YourTestingMID
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of add account holder the command will hold the value “getAccountHolderTokens”. | None | Yes | 30 | A |
accountHolderId | The accountHolder ID that been created for the customer. | _ | No | 25 | AN |
sortOrder | To sort the list of account holder cards in ascending or descending order, possible values are: "asc" and "desc". Please note that the default card will always be the first card on the list | None | No | 4 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of add account holder the command will hold the value “getAccountHolderTokens”. | 30 | A |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | 100 | AN |
permanentCards | A list of all tokens details related to the accountHolderId. | 8000 | AN |
permanentCards.cardToken | The card alias name, that has been assigned to a specific user card | 20 | N |
permanentCards.card | This object contains all the details of the card related to the cardToken. | ||
permanentCards.card.expiryMonth | The card expiry month. | 2 | N |
permanentCards.card.expiryYear | The card expiry year. | 2 | N |
permanentCards.card.cardBin | The bank identification number (BIN) is the initial four to six numbers that appear on a credit card. | 6 | N |
permanentCards.card.cardMaskedNumber | The masked card number of the payer. | 18 | N |
permanentCards.card.cardType | The classification of the payer payment card (i.e., Credit, Debit). | 10 | A |
permanentCards.card.cardBrand | The respective financial institutions (i.e., AMEX, VISA, MasterCard, Discover & JCB). | 15 | A |
permanentCards.card.status | The card status (i.e., VERIFIED) | 20 | A |
permanentCards.card.cardHolderName | The name on the card. | 30 | AN |
responseCode | A code represents the result of the request processing. | 3 | N |
responseMessage | A text that describes the result of the request processing. | 100 | AN |
Delete AccountHolder Token
The delete accountholder token service allows the merchant and partners to delete any payment instruments related to specific accountHolder from MAF Pay.
Gateway URL
Environment | Gateway url |
---|---|
Sandbox | https://payment.sandbox.mafpayments.com/api |
Production | https://payment.mafpayments.com/api |
Note: The sandbox environment is available for integration and compatibility testing of new features before having them available on the production.
Authentication
This API uses basic authentication or Auth0 token along with the partner/merchant identifier to authenticate the requests.
Basic authentication value or the Auth0 authentication token value must be passed in the Authorization header parameter.
Partner or merchant identifiers value must be passed in Partner-Id/Merchant-Id header parameter. MAF Pay provides the credentials required for both parameters.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
PartnerId: YourTestingPID
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlFrVk…
Merchant-Id: YourTestingMID
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of add account holder the command will hold the value “deleteToken”. | None | Yes | 30 | A |
accountHolderId | The accountHolder ID that been created for the customer. | _ | No | 25 | AN |
cardToken | The card alias name, that has been assigned to a specific user card. | None | Yes | 30 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of add account holder the command will hold the value “deleteToken”. | 30 | A |
accountHolderId | The accountHolder ID that been created for the customer. | 25 | AN |
responseCode | A code represents the result of the request processing. | 3 | N |
responseMessage | A text that describes the result of the request processing. | 100 | AN |
Set Default Token
The set default token service allows merchants and partners to assign or change the default card for a particular accountHolder. This service will cancel the current default option on the card (if any) and assign it to the card token in the request.
Gateway URL
Environment | Gateway url |
---|---|
Sandbox | https://payment.sandbox.mafpayments.com/api |
Production | https://payment.mafpayments.com/api |
Note: The sandbox environment is available for integration and compatibility testing of new features before having them available on the production.
Authentication
This API uses basic authentication or Auth0 token along with the partner/merchant identifier to authenticate the requests.
Basic authentication value or the Auth0 authentication token value must be passed in the Authorization header parameter.
Partner or merchant identifiers value must be passed in Partner-Id/Merchant-Id header parameter. MAF Pay provides the credentials required for both parameters.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
PartnerId: YourTestingPID
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlFrVk…
Merchant-Id: YourTestingMID
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of set default card the command will hold the value “setDefaultToken”. | None | Yes | 30 | A |
accountHolderId | The accountHolder ID that been created for the customer. | _ | No | 25 | AN |
cardToken | The card alias name, that has been assigned to a specific user card. | None | Yes | 30 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
responseCode | A code represents the result of the request processing. | 3 | N |
responseMessage | A text that describes the result of the request processing. | 100 | AN |
3D Secure Authentication
3-Domain Secure™ (3D Secure or 3DS) authentication is designed to protect online purchases against card fraud by allowing you to authenticate the payer before completing the submission of Authorize or Pay transaction. 3DS authentication works by authenticating the payer with his card issuer.
3D Secure Flow
What is 3D Secure 2?
3DS2 is the improved standard introduced by EMVCo and the major card schemes. It provides a new approach to authentication through a wider range of data, biometric authentication, and an improved online experience, especially for mobile. It addresses many of 3DS1s issues while bringing benefits across a broader set of use cases for businesses worldwide.
3D Secure 2 Flow
After submitting the payment or card verification request MAF Pay will validate if the card is applicable for 3DS2 authentication, if yes MAF Pay will return the 3D Secure Authentication Identifier value as one of the response parameters, to initiate the 3DS2 authentication you need to pass the 3D Secure Authentication Identifier provided within threeDsAuthId parameter value to the web library in case of web integration or to the mobile SDK in case of mobile app integration.
MAF Pay web library and mobile SDKs will start the process of authenticating the customer and display the issuer 3D Secure 2 page if needed and complete the requested operation in case the customer was successfully authenticated. MAF Pay will return the payment result to the assigned callback along with the valid response.
Please refer to Web Library for more details regarding 3DS2 web integration.
Please refer to iOS SDK for more details regarding 3DS2 iOS integration.
Please refer to Android SDK for more details regarding 3DS2 Android integration.
3D Secure 1 Flow
You will receive the 3D Secure URL as part of the response parameters of the pay/authorize request. To allow your customer to verify their identity using 3D Secure, redirect them to the URL provided within threeDsUrl parameter. Your customer must successfully verify their identity with their card issuer to complete the payment request.
After the completion of the verification process, your customer is redirected back to MAF Pay system. MAF Pay identifies the issuer response and determines if the payment shall be completed or rejected. MAF Pay redirects the customer back to your payment result page redirectUrl along with the valid response.
You will receive pay/authorize response on your transaction feedback URL configured on your merchant account. It is highly advised that you rely on server-to-server notification to receive the payment status as the pay/authorize requests are prone to redirection interruption issues.
Check Transaction Status
You can use check transaction status to retrieve the details of a specific transaction processed through MAF Pay with respect to the unique orderReference, transactionReference and paymentLinkId values.
Gateway URL
Environment | URL |
---|---|
Sandbox | https://query.sandbox.mafpayments.com/api |
Production | https://query.mafpayments.com/api |
Note: The sandbox API is available for integration and compatibility testing of new features before having available on the production environment.
Authentication
This API uses basic authentication and merchant identifier to authenticate the requests, basic authentication value must be passed in the Authorization header parameter and the merchant identifier value must be passed in Merchant-Id header parameter. MAF Pay will provide the credentials required for both parameters.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
Merchant-Id: YourTestingMID
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “checkTransactionStatus”. | None | Yes | 30 | A |
orderReference | The original unique identifier of the payment order. | - , . ,_ | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | - , . ,_ | Yes | 70 | AN |
paymentLinkId | The unique indentifier for the payment link. | None | No | 150 | AN |
Transaction Response
Below table lists all possible response parameters:
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “check_transaction_status”. | 30 | A |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | 70 | AN |
transactionResponseCode | The queried transaction response code. | 3 | N |
transactionResponseMessage | The queried transaction response message. | 100 | AN |
transactionCommand | The queried transaction command. | 30 | A |
gatewayId | A unique reference for the transaction generated by the gateway | 30 | AN |
paymentOption | The selected payment option. | 30 | AN |
amount | A positive integer representing the transaction amount. | 9 | N |
cardToken | The card alias name, that has been assigned to a specific card details. | 30 | AN |
authCode | Identifier for this transaction. | 10 | AN |
currency | Three-letter ISO currency code | 3 | A |
eci | The ecommerce indicator of this transaction. This parameter will hold the value moto. | 10 | A |
description | A text that used by merchants to describe the transaction. | 200 | AN |
responseCode | A code represents the result of the query transaction. | 3 | N |
responseMessage | A text that describes the result of the query transaction. | 100 | AN |
paymentLinkDetails | The list of the payment link details | 5000 | AN |
paymentLinkDetails.id | The unique indentifier for the payment link. | 150 | AN |
paymentLinkDetails.status | The payment link status | 20 | A |
paymentLinkDetails.link | The payment link URL : https://x.x.mafpayments.com/route/payment-link?id=xxxx | 150 | AN |
cardIssuer | The name of the bank that has issued the card. Note this parameter will not be part of the default response. To receive this parameter, please raise a request. |
60 | AN |
cardBin | The bank identification number (BIN) is the initial six numbers that appear on the card. Note this parameter will not be part of the response by default. To activate this parameter, please raise a request. |
6 | N |
cardIssuerCountry | The country of the bank that has issued the card. Note this parameter will not be part of the default response. To receive this parameter, please raise a request. |
60 | AN |
Note: MAF Pay will not return parameters that are not holding a value.
Settlement Services
Acquiring Settlement Upload URL
This section describes the request and response for generating the upload URL that you will use to upload transactions to the system. This URL is valid for specific period of time specified in minutes from the time you receive the successful response.
Gateway URL’s
Environment | URL |
---|---|
Sandbox | https://payment.sandbox.mafpayments.com/api |
production | http://payment.mafpayments.com/api |
Note: The sandbox API is available for integration and compatibility testing of new features before having them on the production environment.
Authentication
This API uses basic authentication and partner identifier to authenticate the requests, basic authentication value must be passed in the Authorization header parameter and the merchant identifier value must be passed in Merchant-Id header parameter. MAF Pay provides the credentials required for both parameters.
Partner Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
Merchant-Id: YourTestingMID
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of add account holder the command will hold the value “getTransactionsUploadURL”. | None | Yes | 30 | A |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of add account holder the command will hold the value “getTransactionsUploadURL”. | 30 | A |
url | This is the URL that you will use to upload the transactions file to MAF Pay system. | 8000 | AN |
expiryMins | The validity of the URL in minutes. | 4 | N |
responseCode | A code represents the result of the request processing. | 3 | N |
responseMessage | A text that describes the result of the request processing. | 100 | AN |
Note: In order to upload the transactions file using the URL provided, you have to use the HTTP method “PUT”.
File Specification and Naming
This section describes the file naming convention, file format and how to upload the transactions file to MAF Pay system.
File format
The transactions file must be in a CSV format (.csv).
File Naming
The file must follow the following naming standard:
<MERCHANT ID>_<YYYYMMDD>_Transactions.csv
Value | Description |
---|---|
MERCHANT ID | Merchant identifier value which been provided by MAF Pay team |
YYYYMMDD | The date of the file in the format of YYYYMMDD:
|
File data fields
Field Name | Description | Length | Type |
---|---|---|---|
contract_id | A unique identifier associated with each beneficiary contract. MAF Pay will provide you with the value. | 50 | AN |
order_reference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | 150 | AN |
transaction_reference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 150 | AN |
sequence_id | A sequential number that links transactions associated with different categories with one transaction_reference. | 10 | AN |
settlement_category | The category name reflecting the fees applied to specific item within the order. | 20 | AN |
operation | The operation name used to process the transaction, possible values are: Pay, Capture, Refund | 10 | A |
amount | A positive integer representing the transaction amount. | 9 | N |
currency | ISO 3166 Alpha-3 code. | 3 | A |
transaction_timestamp | The transaction date and time in ISO 8601 UTC format. | 20 | AN |
Earn and Redeem
Customers who are enrolled in supported loyalty programs can pay and earn for items/services using loyalty points that they have accumulated in those programs.
Earn allows the customer to earn reward points, while redeem allows the customer to use his reward points to pay for the items he wants to purchase.
MAF Pay provides one API which is used to earn and redeem rewards using the supported loyalty programs.
Gateway URL
Environment | Gateway url |
---|---|
Sandbox | https://payment.sandbox.mafpayments.com/api |
Production | https://payment.mafpayments.com/api |
Note: The sandbox environment is available for integration and compatibility testing of new features before having them available on the production.
Authentication
This API uses basic authentication and partner identifier to authenticate the requests, basic authentication value must be passed in the Authorization header parameter and the merchant identifier value must be passed in Merchant-Id header parameter. MAF Pay provides the credentials required for both parameters.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
Merchant-Id: YourTestingMID
Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of earn and redeem the command will hold the value “earnAndRedeem”. | None | Yes | 30 | A |
amount | A positive integer representing the transaction amount. | None | Yes | 9 | N |
currency | ISO 3166 Alpha-3 code | None | Yes | 3 | A |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | - , . ,_ | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | - , . ,_ | Yes | 70 | AN |
redeemAmount | A positive integer representing the rewards redeem amount. | None | Yes | 9 | N |
memberId | The loyalty program membership ID of the user. | None | Yes | 50 | AN |
program | The supported loyalty program that will be used in the earn and redeem process, possible values are: share. | None | Yes | 5 | A |
locationId | The store location ID which was generated by the loyalty program. | None | No | 70 | AN |
sponsorId | The store sponsor ID which was generated by the loyalty program. | None | No | 70 | N |
sku | The list of the items details that the customer selected. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 5000 | AN |
sku.quantity | Quantity of the item selected by the customer. | None | Yes | 9 | N |
sku.itemId | The identifier of the item. | None | Yes | 20 | AN |
sku.unitPrice | The unit price of the item. | None | Yes | 9 | N |
sku.skuLocationId | The store location ID which was generated by the loyalty program. | None | No | 70 | AN |
originalAmount | A positive integer representing the original amount. | None | No | 9 | N |
Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of earn and redeem the command will hold the value “earnAndRedeem”. | 30 | A |
amount | A positive integer representing the transaction amount. | 9 | N |
currency | ISO 3166 Alpha-3 code | 3 | A |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
redeemAmount | A positive integer representing the rewards redeem amount. | 9 | N |
memberId | The loyalty program membership ID of the user. | 50 | AN |
program | The supported loyalty program that will be used in the earn and redeem process, possible values are: share. | 5 | A |
locationId | The store location ID which was generated by the loyalty program. | 70 | AN |
sponsorId | The store sponsor ID which was generated by the loyalty program. | 70 | N |
pointsEarned | The reward points earned. | 70 | N |
pointsRedeemed | The reward points redeemed. | 70 | N |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
Reversal
You can reverse point redemption and earnt point associated with a specific redeem and earn transaction.
Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of reversal the command will hold the value “reversal”. | None | Yes | 30 | A |
orderReference | The original unique identifier of the payment order. | None | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | None | Yes | 70 | AN |
Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of reversal the command will hold the value “reversal”. | 30 | A |
orderReference | The original unique identifier of the payment order. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
Partial Reversal
You can partially reverse point redeemed and earned associated with a specific transaction.
Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of partial reversal the command will hold the value “partialReversal”. | None | Yes | 30 | A |
orderReference | The original unique identifier of the payment order. | None | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | None | Yes | 70 | AN |
sku | The list of the items details that the customer selected. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 5000 | AN |
sku.quantity | Quantity of the item selected by the customer. | None | Yes | 9 | N |
sku.itemId | The identifier of the item. | None | Yes | 20 | AN |
Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of reversal the command will hold the value “reversal”. | 30 | A |
orderReference | The original unique identifier of the payment order. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
Carrefour Gift Card
Customers who have Carrefour gift card can pay for items/services using this card, those cards are B2C cards that allow customers to pay for their purchases online and offline.
Check Balance allows the merchant to check the customers gift card balance, while redeem allows them to deduct money from their customers gift card against their purchases, and reverse operation is used reverse redemption associated with a specific redeem transaction.
MAF Pay provides one API which is used to check card balance, redeem points and reverse transactions using the supported gift card processor.
Gateway URL
Environment | Gateway url |
---|---|
Sandbox | https://payment.sandbox.mafpayments.com/api |
Production | https://payment.mafpayments.com/api |
Note: The sandbox environment is available for integration and compatibility testing of new features before having them available on the production.
Authentication
This API uses basic authentication and merchant identifier to authenticate the requests, basic authentication value must be passed in the Authorization header parameter and the merchant identifier value must be passed in Merchant-Id header parameter. MAF Pay provides the credentials required for both parameters.
Header Example
Authorization: Your testing authentication header Example (Basic YfreaDEyMjFRdhdXRoMTIz)
Merchant-Id: YourTestingMID
Check Balance
You can use check balance to check the customers gift card balance.
Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of check balance the command will hold the value “checkBalance”. | None | Yes | 12 | A |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | - , . ,_ | Yes | 40 | AN |
description | A text that used by merchants to describe the transaction. | None | No | 200 | AN |
cardNumber | String contains the card number for the owner of the gift card, example value is 8205178202769139. | None | Yes | 16 | AN |
pinCode | Pin code associated with the card. | None | No | 40 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response, if sent in the request. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of check balance the command will hold the value “checkBalance”. | 30 | A |
balance | A positive integer representing the balance the card hold. | 9 | N |
currency | ISO 3166 Alpha-3 code | 3 | A |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | 70 | AN |
description | A text that used by merchants to describe the transaction. | 200 | AN |
expiryMonth | The card expiry month. | 2 | N |
expiryYear | The card expiry year. | 2 | N |
cardType | A string that represent card type which might contains on of the following values 0 (Gift Card), 1(Loyalty Card), 2 (Charity Card), 3(Promo Card), 4(Affinity Card), 5(Payment Card). | 50 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response, if sent in the request. | 200 | AN |
Redeem
Redeem is the act of deducting from your card balance in order to pay for items or product at cashier location.
Request
Parameter Name | Description | Required | Length | Type |
---|---|---|---|---|
command | The operation name requested, in case of reversal the command will hold the value “redeem”. | Yes | 6 | A |
orderReference | The original unique identifier of the payment order. | Yes | 40 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | Yes | 70 | AN |
currency | ISO 3166 Alpha-3 code | Yes | 3 | A |
amount | A positive integer representing the transaction amount. | Yes | 9 | N |
cardNumber | String contains the card number for the owner of the gift card, example value is 8205178202769139. | Yes | 16 | AN |
pinCode | Pin code associated with the card. | No | 40 | AN |
description | A text that used by merchants to describe the transaction. | No | 200 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response, if sent in the request. | No | 200 | AN |
Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of reversal the command will hold the value “redeem”. | 30 | A |
orderReference | The original unique identifier of the payment order. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
description | A text that used by merchants to describe the transaction. | 200 | AN |
amount | A positive integer representing the redeem amount. | 9 | N |
balance | A positive integer representing the balance after amount deduction. | 9 | N |
currency | ISO 3166 Alpha-3 code | 3 | A |
cardType | A string that represent card type which might contains on of the following values 0 (Gift Card), 1(Loyalty Card), 2 (Charity Card), 3(Promo Card), 4(Affinity Card), 5(Payment Card). | 50 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response, if sent in the request. | 200 | AN |
Reverse Redemption
You can reverse balance redeemed, we are either going to cancel the transaction and refund the user or void the transaction and refund the user afterwards.
Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of partial reversal the command will hold the value “reverseRedemption”. | None | Yes | 30 | A |
orderReference | The original unique identifier of the payment order. | None | Yes | 40 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | None | Yes | 70 | AN |
description | A text that used by merchants to describe the transaction. | None | No | 200 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response, if sent in the request. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of reversal the command will hold the value “reverseRedemption”. | 30 | A |
orderReference | The original unique identifier of the payment order. | 40 | AN |
description | A text that used by merchants to describe the transaction. | 200 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
balance | A positive integer representing the balance after reversing the redeem amount. | 9 | N |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response, if sent in the request. | 200 | AN |
Maintenance Operations
Capture
After authorizing a payment, you can capture the authorized amount from the customer account to your account by using capture operation against the authorized payment.
Authentication
This API uses basic authentication and merchant identifier to authenticate the requests, basic authentication value must be passed in the Authorization header parameter and the merchant identifier value must be passed in Merchant-Id header parameter. MAF Pay will provide the credentials required for both parameters.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
Merchant-Id: YourTestingMID
Gateway URL
Environment | URL |
---|---|
Sandbox | https://payment.sandbox.mafpayments.com/api |
Production | https://payment.mafpayments.com/api |
Note: The sandbox API is available for integration and compatibility testing of new features before having available on the production environment.
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value "capture". | None | Yes | 30 | A |
orderReference | The original unique identifier of the payment order. | - , . ,_ | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | - , . ,_ | Yes | 70 | AN |
amount | A positive integer representing the transaction amount. | None | Yes | 9 | N |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
Note: If the payment option is Spotii, partial capture is not allowed; therefore, capture amount must match authorization amount.
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “capture”. | 30 | A |
orderReference | The original unique identifier of the payment order. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
amount | A positive integer representing the transaction amount. | 9 | N |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | 200 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
Refund
You can use refund operation against the captured amount through pay or capture transaction.
Authentication
This API uses basic authentication and merchant identifier to authenticate the requests, basic authentication value must be passed in the Authorization header parameter and the merchant identifier value must be passed in Merchant-Id header parameter. MAF Pay will provide the credentials required for both parameters.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
Merchant-Id: YourTestingMID
Gateway URL
Environment | URL |
---|---|
Sandbox | https://payment.sandbox.mafpayments.com/api |
Production | https://payment.mafpayments.com/api |
Note: The sandbox API is available for integration and compatibility testing of new features before having available on the production environment.
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value "refund". | None | Yes | 30 | A |
orderReference | The original unique identifier of the payment order. | - , . ,_ | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | - , . ,_ | Yes | 70 | AN |
amount | A positive integer representing the transaction amount. | None | Yes | 9 | N |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “refund”. | 30 | A |
orderReference | The original unique identifier of the payment order. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
amount | A positive integer representing the transaction amount. | 9 | N |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | 200 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
Void
You can use void operation to cancel the hold placed on funds through the authorization.
Authentication
This API uses basic authentication and merchant identifier to authenticate the requests, basic authentication value must be passed in the Authorization header parameter and the merchant identifier value must be passed in Merchant-Id header parameter. MAF Pay will provide the credentials required for both parameters.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
Merchant-Id: YourTestingMID
Gateway URL
Environment | URL |
---|---|
Sandbox | https://payment.sandbox.mafpayments.com/api |
Production | https://payment.mafpayments.com/api |
Note: The sandbox API is available for integration and compatibility testing of new features before having available on the production environment.
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value "void". | None | Yes | 30 | A |
orderReference | The original unique identifier of the payment order. | - , . ,_ | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | - , . ,_ | Yes | 70 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “void”. | 30 | A |
orderReference | The original unique identifier of the payment order. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | 200 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
Void Refund
You can use void refund operation to cancel the last refund performed.
Authentication
This API uses basic authentication and merchant identifier to authenticate the requests, basic authentication value must be passed in the Authorization header parameter and the merchant identifier value must be passed in Merchant-Id header parameter. MAF Pay will provide the credentials required for both parameters.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
Merchant-Id: YourTestingMID
Gateway URL
Environment | URL |
---|---|
Sandbox | https://payment.sandbox.mafpayments.com/api |
Production | https://payment.mafpayments.com/api |
Note: The sandbox API is available for integration and compatibility testing of new features before having available on the production environment.
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of void refund the command will hold the value "voidRefund". | None | Yes | 30 | A |
orderReference | The original unique identifier of the payment order. | - , . ,_ | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | - , . ,_ | Yes | 70 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of Void Refund the command will hold the value “voidRefund”. | 30 | A |
orderReference | The original unique identifier of the payment order. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
Close
You can use close operation to close the TABBY transactions. Closed is the final status of the payment. Your payment is going to be closed automatically if you capture the full amount of the payment. If only a part of the order is delivered, please capture this part and close the payment – it will mean that another part of the order is not going to be delivered to the customer.
Authentication
This API uses basic authentication and merchant identifier to authenticate the requests, basic authentication value must be passed in the Authorization header parameter and the merchant identifier value must be passed in Merchant-Id header parameter. MAF Pay will provide the credentials required for both parameters.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
Merchant-Id: YourTestingMID
Gateway URL
Environment | URL |
---|---|
Sandbox | https://payment.sandbox.mafpayments.com/api |
Production | https://payment.mafpayments.com/api |
Note: The sandbox API is available for integration and compatibility testing of new features before having available on the production environment.
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value "close". | None | Yes | 30 | A |
orderReference | The original unique identifier of the payment order. | - , . ,_ | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | - , . ,_ | Yes | 70 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “close”. | 30 | A |
orderReference | The original unique identifier of the payment order. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | 200 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
SVF Wallet
Authentication
Wallet API uses basic authentication and merchant identifier to authenticate the requests, basic authentication value must be passed in the Authorization header parameter and the merchant identifier value must be passed in Merchant-Id header parameter. MAF Pay will provide the credentials required for both parameters.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
Merchant-Id: YourTestingMID
Gateway URL
Environment | URL |
---|---|
Sandbox | https://wallet.sandbox.mafpayments.com/api |
Production | https://wallet.mafpayments.com/api |
Note: The sandbox API is available for integration and compatibility testing of new features before having available on the production environment.
Create User
Create a SVF wallet user that can be linked to user wallet account.
Transaction Request
MAF Pay | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of creating new user the command will hold the value "createUser". | None | Yes | 30 | A |
customerEmail | The user email address. | - . _ @ | No | 100 | AN |
customerFirstName | The user first name | - . < > " ' | Yes | 100 | A |
customerLastName | The user last name | - . < > " ' | Yes | 100 | A |
customerPhone | The user phone number. | + | No | 16 | N |
userId | The unique user ID that identify the user. | | - _ . | Yes | 50 | AN |
accountId | The unique account ID that identify the user account. | | - _ . | No | 50 | AN |
currency | ISO 3166 Alpha-3 code of the account currency | None | No | 3 | A |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of creating new user the command will hold the value "createUser". | 30 | A |
customerEmail | The user email address. | 100 | AN |
customerFirstName | The user first name. | 100 | A |
customerLastName | The user first name. | 100 | A |
customerPhone | The user phone number. | 16 | N |
userId | The unique user ID that identify the user. | 50 | AN |
status | It represent the status of the user (i.e., active, suspended, blocked, and deleted). | 20 | A |
accountId | The unique account ID that identify the user account. | No | 50 |
currency | ISO 3166 Alpha-3 code of the account currency | No | 3 |
responseCode | A code represents the result of the request processing. | 3 | N |
responseMessage | A text that describes the result of the request processing. | 100 | AN |
Get User
View user information, along with his/her accounts.
Transaction Request
MAF Pay | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of creating new user the command will hold the value "getUser". | None | Yes | 30 | A |
userId | The unique user ID that identify the user. | | - _ . | Yes | 50 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of creating new user the command will hold the value "getUser". | 30 | A |
customerEmail | The user email address. | 100 | AN |
customerFirstName | The user first name. | 100 | A |
customerLastName | The user first name. | 100 | A |
customerPhone | The user phone number. | 16 | N |
userId | The unique user ID that identify the user. | 50 | AN |
status | It represent the status of the user (i.e., active, suspended, blocked, and deleted). | 20 | A |
responseCode | A code represents the result of the request processing. | 3 | N |
responseMessage | A text that describes the result of the request processing. | 100 | AN |
accounts[].accountId | The unique account ID that identify the user account. | 50 | AN |
accounts[].reservedAmount | Locked or reserved funds in the account due to authorizations. | 9 | N |
accounts[].balance | Balance of the account. | 9 | N |
accounts[].accountType | Account Type ID. If not sent, a default account type will be used based on system configurations, possible values are : 1. customer |
64 | N |
accounts[].description | Description of the account. | 250 | AN |
accounts[].currency | ISO 3166 Alpha-3 code of the account currency. | 3 | A |
accounts[].status | It represent the status of the account (i.e., active, suspended, blocked, and deleted). | 20 | A |
Create Account
Create a new SVF wallet account with a specific type. The account is created as active and fully functional. This API can be used to create an account and directly link it to an existing users.
Transaction Request
MAF Pay | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of creating new account the command will hold the value "createAccount". | None | Yes | 30 | A |
accountId | The unique account ID that identify the user account. | | - _ . | No | 50 | AN |
accountType | Account Type ID. If not sent, a default account type will be used based on system configurations, possible values are : 1. customer |
None | No | 64 | N |
alias | Alias name of the account. | - _ . " ' | No | 100 | AN |
currency | ISO 3166 Alpha-3 code of the account currency | None | No | 3 | A |
description | Description of the account. | Space | No | 250 | AN |
userId | The unique user ID that identify the user. | | - _ . | Yes | 50 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of creating new account the command will hold the value "createAccount". | 30 | A |
accountId | The unique account ID that identify the user account. | 50 | AN |
accountType | Account Type ID. If not sent, a default account type will be used based on system configurations, possible values are : 1. customer |
64 | N |
alias | Alias name of the account. | 100 | AN |
currency | ISO 3166 Alpha-3 code of the account currency. | 3 | A |
description | Description of the account. | 250 | AN |
userId | The unique user ID that identify the user. | 50 | AN |
balance | Balance of the account. | 9 | N |
reservedAmount | Locked or reserved funds in the account due to authorizations. | 9 | N |
status | It represent the status of the account (i.e., active, suspended, blocked, and deleted). | 20 | A |
responseCode | A code represents the result of the request processing. | 3 | N |
responseMessage | A text that describes the result of the request processing. | 100 | AN |
Account Balance
Returns the SVF wallet account available balance.
Transaction Request
MAF Pay | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of retrieving account balance the command will hold the value "accountBalance". | None | Yes | 30 | A |
accountId | The unique account ID that identify the user account. | | - _ . | Yes | 50 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of retrieving account balance the command will hold the value "accountBalance". | 30 | A |
accountId | The unique account ID that identify the user account. | 50 | AN |
balance | Balance of the account. | 9 | N |
reservedAmount | Locked or reserved funds in the account due to authorizations. | 9 | N |
responseCode | A code represents the result of the request processing. | 3 | N |
responseMessage | A text that describes the result of the request processing. | 100 | AN |
Account TopUp
Transfer funds from 'General TopUp Account' to a specific customer wallet account. The customer wallet account funds balance is increased and the transferred funds instantly become available for further customer transaction.
Transaction Request
MAF Pay | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of top up an account the command will hold the value "topUp". | None | Yes | 30 | A |
amount | Positive integer representing the transaction amount, the amount value have to be multiplied by the currency decimal code according to ISO code 3. | None | Yes | 9 | N |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | _ - . | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | _ - . | No | 70 | AN |
description | A text that used by merchants to describe the transaction. | Space | No | 200 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | Space ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ { | } ~ | No | 200 | AN |
fundingType | Type of top up, possible values are: 1.bank 2.refund 3.card 4.agent 5.atm |
None | Yes | 10 | A |
accountId | The unique account ID that identify the user account. | | - _ . | Yes | 50 | AN |
customerIp | Customer IP address. | . | No | 50 | N |
userId | The unique user ID that identify the user . | | - _ . | No | 50 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of top up an account the command will hold the value "topUp". | 30 | A |
amount | Positive integer representing the transaction amount, the amount value have to be multiplied by the currency decimal code according to ISO code 3. | 9 | N |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
description | A text that used by merchants to describe the transaction. | 200 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | 200 | AN |
fundingType | Type of top up, possible values are: 1.bank 2.refund 3.card 4.agent 5.atm |
10 | A |
accountId | The unique account ID that identify the user account. | 50 | AN |
customerIp | Customer IP address. | 50 | N |
userId | The unique user ID that identify the user. | 50 | AN |
currency | Three-letter ISO currency code. | 3 | A |
accountType | Account Type ID. If not sent, a default account type will be used based on system configurations, possible values are : 1. customer |
64 | N |
balance | Balance of the account. | 9 | N |
reservedAmount | Locked or reserved funds in the account due to authorizations. | 9 | N |
gatewayId | A unique reference for the transaction generated by the gateway. | 30 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
Adjust Debit
Perform a debit transaction on a customer wallet account to a 'General Adjustments Account'.
Transaction Request
MAF Pay | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of adjusting debit of an account the command will hold the value "adjustDebit". | None | Yes | 30 | A |
amount | Positive integer representing the transaction amount, the amount value have to be multiplied by the currency decimal code according to ISO code 3. | None | Yes | 9 | N |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | _ - . | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | _ - . | No | 70 | AN |
description | A text that used by merchants to describe the transaction. | Space | No | 200 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | Space ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ { | } ~ | No | 200 | AN |
originalOrderReference | The original unique identifier for the debit order. | _ - . | No | 70 | AN |
accountId | The unique account ID that identify the user account. | | - _ . | Yes | 50 | AN |
customerIp | Customer IP address. | . | No | 50 | N |
userId | The unique user ID that identify the user . | | - _ . | No | 50 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of adjusting debit of an account the command will hold the value "adjustDebit". | 30 | A |
amount | Positive integer representing the transaction amount, the amount value have to be multiplied by the currency decimal code according to ISO code 3. | 9 | N |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
description | A text that used by merchants to describe the transaction. | 200 | AN |
originalOrderReference | The original unique identifier for the debit order. | 70 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | 200 | AN |
accountId | The unique account ID that identify the user account. | 50 | AN |
customerIp | Customer IP address. | 50 | N |
userId | The unique user ID that identify the user. | 50 | AN |
currency | Three-letter ISO currency code. | 3 | A |
accountType | Account Type ID. If not sent, a default account type will be used based on system configurations, possible values are : 1. customer |
64 | N |
balance | Balance of the account. | 9 | N |
reservedAmount | Locked or reserved funds in the account due to authorizations. | 9 | N |
gatewayId | A unique reference for the transaction generated by the gateway. | 30 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
Adjust Credit
Perform a credit transaction on a customer wallet account from a 'General Adjustments Account'
Transaction Request
MAF Pay | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of adjusting credit of an account the command will hold the value "adjustCredit". | None | Yes | 30 | A |
amount | Positive integer representing the transaction amount, the amount value have to be multiplied by the currency decimal code according to ISO code 3. | None | Yes | 9 | N |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | _ , - , . | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | _ , - , . | No | 70 | AN |
description | A text that used by merchants to describe the transaction. | Space | No | 200 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | Space ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ { | } ~ | No | 200 | AN |
originalOrderReference | The original unique identifier for the debit order. | _ - . | No | 70 | AN |
accountId | The unique account ID that identify the user account. | | - _ . | Yes | 50 | AN |
customerIp | Customer IP address. | . | No | 50 | N |
userId | The unique user ID that identify the user . | | - _ . | No | 50 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of adjusting credit of an account the command will hold the value "adjustCredit". | 30 | A |
amount | Positive integer representing the transaction amount, the amount value have to be multiplied by the currency decimal code according to ISO code 3. | 9 | N |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
description | A text that used by merchants to describe the transaction. | 200 | AN |
originalOrderReference | The original unique identifier for the debit order. | 70 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | 200 | AN |
accountId | The unique account ID that identify the user account. | 50 | AN |
customerIp | Customer IP address. | 50 | N |
userId | The unique user ID that identify the user. | 50 | AN |
currency | Three-letter ISO currency code. | 3 | A |
accountType | Account Type ID. If not sent, a default account type will be used based on system configurations, possible values are : 1. customer |
64 | N |
balance | Balance of the account. | 9 | N |
reservedAmount | Locked or reserved funds in the account due to authorizations. | 9 | N |
gatewayId | A unique reference for the transaction generated by the gateway. | 30 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
Payment
Perform a debit transaction on a customer wallet account decreasing the available balance and crediting 'General Purchase Account'.
Transaction Request
MAF Pay | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of payment the command will hold the value "pay". | None | Yes | 30 | A |
amount | Positive integer representing the transaction amount, the amount value have to be multiplied by the currency decimal code according to ISO code 3. | None | Yes | 9 | N |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | _ - . | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | _ - . | No | 70 | AN |
description | A text that used by merchants to describe the transaction. | Space | No | 200 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | Space ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ { | } ~ | No | 200 | AN |
accountId | The unique account ID that identify the user account. | | - _ . | Yes | 50 | AN |
customerIp | Customer IP address. | . | No | 50 | N |
userId | The unique user ID that identify the user . | | - _ . | No | 50 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of payment the command will hold the value "pay". | 30 | A |
amount | Positive integer representing the transaction amount, the amount value have to be multiplied by the currency decimal code according to ISO code 3. | 9 | N |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
description | A text that used by merchants to describe the transaction. | 200 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | 200 | AN |
accountId | The unique account ID that identify the user account. | 50 | AN |
customerIp | Customer IP address. | 50 | N |
userId | The unique user ID that identify the user. | 50 | AN |
currency | Three-letter ISO currency code | 3 | A |
accountType | Account Type ID. If not sent, a default account type will be used based on system configurations, possible values are : 1. customer |
64 | N |
balance | Balance of the account. | 9 | N |
reservedAmount | Locked or reserved funds in the account due to authorizations. | 9 | N |
gatewayId | A unique reference for the transaction generated by the gateway. | 30 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
CashOut
Transfer funds from a customer wallet account to a 'Cash, Card, ATM or Bank General Cash-out Account'.
Transaction Request
MAF Pay | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of cash out the command will hold the value "cashOut". | None | Yes | 30 | A |
amount | Positive integer representing the transaction amount, the amount value have to be multiplied by the currency decimal code according to ISO code 3. | None | Yes | 9 | N |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | _ - . | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | _ - . | No | 70 | AN |
fundingType | Type of top up, possible values are: 1.bank 2.refund 3.card 4.agent 5.atm |
None | Yes | 10 | A |
description | A text that used by merchants to describe the transaction. | Space | No | 200 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | Space ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ { | } ~ | No | 200 | AN |
accountId | The unique account ID that identify the user account. | | - _ . | Yes | 50 | AN |
customerIp | Customer IP address. | . | No | 50 | N |
userId | The unique user ID that identify the user . | | - _ . | No | 50 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of cash out the command will hold the value "cashOut". | 30 | A |
amount | Positive integer representing the transaction amount, the amount value have to be multiplied by the currency decimal code according to ISO code 3. | 9 | N |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
fundingType | Type of top up, possible values are: 1.bank 2.refund 3.card 4.agent 5.atm |
10 | A |
description | A text that used by merchants to describe the transaction. | 200 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | 200 | AN |
accountId | The unique account ID that identify the user account. | 50 | AN |
customerIp | Customer IP address. | 50 | N |
userId | The unique user ID that identify the user. | 50 | AN |
currency | Three-letter ISO currency code | 3 | A |
accountType | Account Type ID. If not sent, a default account type will be used based on system configurations, possible values are : 1. customer |
64 | N |
balance | Balance of the account. | 9 | N |
reservedAmount | Locked or reserved funds in the account due to authorizations. | 9 | N |
gatewayId | A unique reference for the transaction generated by the gateway. | 30 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
Peer To Peer Transfer
Transfer funds between 2 accounts. The receiver wallet account funds balance is increased and the sender wallet account funds balance is decreased and the transferred funds instantly become available for further account transactions
Transaction Request
MAF Pay | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of peer to peer transfer the command will hold the value "transfer". | None | Yes | 30 | A |
amount | Positive integer representing the transaction amount, the amount value have to be multiplied by the currency decimal code according to ISO code 3. | None | Yes | 9 | N |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | _ - . | Yes | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | _ - . | No | 70 | AN |
description | A text that used by merchants to describe the transaction. | Space | No | 200 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | Space ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ { | } ~ | No | 200 | AN |
destinationAccountId | The receiver account ID | | - _ . | Yes | 50 | AN |
accountId | The unique account ID that identify the user account. | | - _ . | Yes | 50 | AN |
customerIp | Customer IP address. | . | No | 50 | N |
userId | The unique user ID that identify the user . | | - _ . | No | 50 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of top up an account the command will hold the value "topUp". | 30 | A |
amount | Positive integer representing the transaction amount, the amount value have to be multiplied by the currency decimal code according to ISO code 3. | 9 | N |
orderReference | The unique identifier for the payment order. The merchant is responsible for generating this reference. | 70 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
description | A text that used by merchants to describe the transaction. | 200 | AN |
extraData | A metadata parameter that can be used to attach specific values to this transaction, this parameter will always return in the response. | 200 | AN |
destinationAccountId | The receiver account ID | 50 | AN |
accountId | The unique account ID that identify the user account. | 50 | AN |
customerIp | Customer IP address. | 50 | N |
userId | The unique user ID that identify the user. | 50 | AN |
currency | Three-letter ISO currency code. | 3 | A |
accountType | Account Type ID. If not sent, a default account type will be used based on system configurations, possible values are : 1. customer |
64 | N |
balance | Balance of the account. | 9 | N |
reservedAmount | Locked or reserved funds in the account due to authorizations. | 9 | N |
gatewayId | A unique reference for the transaction generated by the gateway. | 30 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
Transaction History
Returns a list of successful transactions within a selected date and time range for a specific SVF user wallet account.
Transaction Request
MAF Pay | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of retrieving account transactions the command will hold the value "transactionHistory". | None | Yes | 30 | A |
accountId | The unique account ID that identify the user account. | | - _ . | Yes | 50 | AN |
transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | _ - . | No | 70 | AN |
userId | The unique user ID that identify the user . | | - _ . | No | 50 | AN |
dateFrom | The beginning date of the transactions required, the default timezone is GMT, example: 08-07-2021T18:00:00+0300 . | : - . + | No | 25 | AN |
dateTo | The end date of the transactions required, the default timezone is GMT, example: 08-07-2021T18:00:00+0300 . | : - . + | No | 25 | AN |
pageNumber | The required page number | None | No | 5 | N |
pageSize | The number of transactions per page. | None | No | 5 | N |
sortDirection | The type of sort that will be applied, possible values are: 1. asc 2. desc |
None | No | 10 | A |
orderReference | The unique identifier for the top up order. The merchant is responsible for generating this reference. | _ - . | No | 70 | AN |
transactionResponseCode | The unique identifier for each transaction. The merchant is responsible for generating this reference. | None | No | 4 | N |
transactionType | The operation name requested, possible values are: 1. topUp 2. pay 3. cashOut 4. adjustCredit 5. adjustDebit |
None | No | 30 | A |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of retrieving account transactions the command will hold the value "transactionHistory". | 30 | A |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 100 | AN |
transactions[].accountId | The unique account ID that identify the user account. | 50 | AN |
transactions[].amount | Positive integer representing the transaction amount, the amount value have to be multiplied by the currency decimal code according to ISO code 3. | 9 | N |
transactions[].orderReference | The unique identifier for the top up order. The merchant is responsible for generating this reference. | 70 | AN |
transactions[].transactionReference | The unique identifier for each transaction. The merchant is responsible for generating this reference. | 70 | AN |
transactions[].originalOrderReference | The original unique identifier for the order. | 70 | AN |
transactions[].gatewayId | A unique reference for the transaction generated by the gateway. | 30 | AN |
transactions[].description | A text that used by merchants to describe the transaction. | 200 | AN |
transactions[].currency | ISO 3166 Alpha-3 code of the account currency | 3 | A |
transactions[].fundingType | Type of top up, possible values are: 1.bank 2.refund 3.card 4.agent 5.atm |
10 | A |
transactions[].responseCode | A code represents the result of the request processing. | 3 | N |
transactions[].timestamp | The date of the processed request. | 25 | AN |
transactions[].command | The operation name requested. | 30 | A |
transactions[].userId | The unique user ID that identify the user. | 50 | AN |
transactions[].balance | Balance of the account. | 9 | N |
transactions[].reservedAmount | Locked or reserved funds in the account due to authorizations. | 9 | N |
pageInfo.hasTransactions | Indicator if the page has transactions records. | 5 | A |
pageInfo.hasNext | Indicator if there is a next page. | 5 | A |
pageInfo.hasPrevious | Indicator if this is the previous page. | 5 | A |
pageInfo.first | Indicator if this is the first page. | 5 | A |
pageInfo.last | Indicator if this is the last page. | 5 | A |
pageInfo.numberOfTransactions | The number of transactions in this page. | 5 | N |
pageInfo.pageNumber | The current page number. | 5 | N |
pageInfo.pageSize | The number of transactions per page. | 5 | N |
pageInfo.totalTransactions | The total number of the transactions in all pages. | 5 | N |
pageInfo.totalPages | The total number of the pages. | 5 | N |
SDKS
iOS SDK
Requirements
The MAF Pay iOS SDK supports swift language and is compatible with Apps targeting iOS 11 or above.
Getting Started
Installation using Cocoapods
The SDK is distributed as an XCFramework, therefore you are required to use Cocoapods 1.9.0 or newer.
a. Add the following to your Podfile (inside the target section):
pod 'MAFPay'
b. Add the following to the bottom of your Podfile:
post_install do |installer|
installer.pods_project.targets.each do |target|
if ['MAFPay','Alamofire'].include? target.name
target.build_configurations.each do |config|
config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
end
end
end
end
c. Run pod install
Setup the SDK
In order to use MAF Pay iOS SDK you must add the below code in your AppDelegate class:
import MAFPay
/**
Setup a shared values in order to using them while calling the tokenize endpoints
- Parameter apiEnviroment: The object carries the api environment (such as Staging and Production)
- Parameter apiKey: An optional value, a unique identifier used to authenticate a merchant or partner.
- Parameter merchantId: An optional value merchantId, a unique identifier used to authenticate a merchant.
- Parameter partnerId: An optional value partnerId, a unique identifier used to authenticate a partner.
- Parameter isLoggerActive: a Boolean value determine whether response body data should be logged.
This func is mandatory for tokenization process
*/
public static func setup(with apiEnviroment: Enviroment, apiKey: String = "", merchantId: String? = nil, partnerId: String? = nil, isLoggerActive: Bool = false)
/**
- JWT token of the authentication provider, for now we only support Auth0 authentication management system
MAFPay.authorizedKey = “<JWT Token Value>”
Setup the environment
To setup the correct environment you can use environment parameter. Environment is as enum returns all supported enviroments in the SDK. The object contains the following cases:
case production
case sandbox
Setup the language
To setup the required language you can use language parameter. MAFPayLanguage is as enum returns all supported languages in the SDK. The object contains the following cases:
enum MAFPayLanguage: String {
case arabic =
case English
}
Example:
MAFPay.language = .arabic
MAFPay.language = .english
MAF Pay Card Components
MAF Pay UI components securely collects your customer’s payment card details.
Components Items
- CardView: is the parent view of the other views such as cardNumber, holderName, cvcNumber, and expiryDate.
- cardNumber: you will use this view to collect customer card number
- holderName: you will use this view to collect customer card holder name
- cvcNumber: you will use this view to collect customer card security code
- expiryDate: you will use this view to collect customer card expiry date
- RememberCardView: This component is built to enable or disabled storing the customer payment card
- TokenizeButton: this button submits the payment form data to MAF Pay.
- MirrorView: these UI components are built to mirror the input text of card view items.
- CVCHintButton : this UI component used to show a CVC hint as a popup message.
Components Setup
Card item initializer parameters:- itemType: the type of the view, possible values are:
- cardNumber
- holderName
- cvcNumber
- expiryDate
- iconTextFieldPosition: the icon text field position inside the inputTextField.
The below example shows how to setup a view item in your application:
open func setupView(as itemType: ItemType, iconTextFieldPosition: IconTextFieldPosition? = nil)
Card verification setup
TokenizeButton contains one property “verificationType”, below is description of flow based on the property value :
- No Verification: If the property value is set to “none” which is the default property value, MAF Pay will ONLY tokenize the card.
- 3DS Authentication: If the property value is “threeDs”, the card 3DS enrolment check is initiated, if the card is enrolled MAF Pay will redirect the user to the issuer page for authentication. If the 3DS check fails or the 3DS authentication fails MAF Pay will not tokenize the card.
- Random Amount deduction: If the property value is “rndAmount”, MAF Pay will tokenize the card, deduct a random amount from the card. You can pass the value of cardToken in the confirmVerification operation to verify the card.
Set card as default
TokenizeButton contains a property “isDefaultCard” which takes a Boolean value to indicate whether the card will be the default card.
btnToknaize.isDefaultCard = true
Set card for recurring
TokenizeButton contains a property “isRecurring” which takes a Boolean value to indicate whether the card will be used in processing recurring transactions
Note: you have to send verifyCard = .threeDs3ds along with isRecurring=true parameters
btnToknaize.isRecurring = true
Card verification setup (deprecated)
TokenizeButton contains one property “tokanizeWithVerify” which takes a Boolean value to indicate whether the card will be verified using the Random Amount Deduction.
View Component Options and Functions
Option | Type | Description |
---|---|---|
delegate | PMCardDelegate | Passes the result of the card error detector to the delegate. |
textFieldFontStyle | UIFont | The font of the input text field. The default value is nil, which uses the default system font (17 pt). |
placeholderText | String | The string which will be displayed if the input text field is empty. The default value is nil. The placeholder string color will be the system-defined color. |
placeholderAttributedString | NSAttributedString | The styled string which will be displayed if the input text field is empty. The default value is nil. The placeholder string color will be the system-defined color and the remaining style information (except the text color) of the attributed string. |
textFieldBorderStyle | UITextField.BorderStyle | The border style used by the input text field. The default value for this property is UITextField.BorderStyle.none. If the value is set to the UITextField.BorderStyle.roundedRect style, the custom background image associated with the text field is ignored. |
textFieldBackgroundColor | UIColor | The background color of the input text field. This property can be animated. The default value is nil, which results in a transparent background color. |
textFieldFontColor | UIColor | The text color of the input text field. This property applies to the entire text string. The default value for this property is a black color. |
textFieldTintColor | UIColor | The first nondefault tint color value in the view’s hierarchy, ascending from and starting with the view itself. If the system cannot find a nondefault color in the hierarchy, this property’s value is a system-defined color instead. |
textFieldIsSecureTextEntry | Bool | Identifies whether the text object should disable text copying and in some cases hide the text being entered. This property is set to false by default. |
textFieldReturnKeyType | UIReturnKeyType | The visible title of the Return key. Setting this property to a different key type changes the visible title of the Return key and typically results in the keyboard being dismissed when it is pressed. The default value for this property is UIReturnKeyType.default. |
textFieldTextAlignment | NSTextAlignment | The technique to use for aligning the text. This property applies to the both the main text string and the placeholder string. |
separatorCharacter | String | The separator character of the card numbers digits or expiry date based on item kind. This value will read just one Character, if you set more that one the property will choose the first one, The default value for card numbers is single space and for expiry date is "/" |
cardBrandImages | CardBrandImages | The object carries a credit-card brands (such as Visa and MasterCard). This property carried two brands (Visa and MasterCard) by default and ability to change one or both of them |
errorText | String | The text displayed in the error label if label is added. The default value for this property is dynamic text based on Card error detector |
disableErrorMessage | Bool | A Boolean value that determines whether the error label is hidden. This property will not be active if the error label does not added. This property is set to false by default. |
showErrorMessageType | ShowErrorMessage | The error message displaying type. This property carried two types:endTyping, whileTyping. This property is set to endTyping by default. |
textFieldErrorTextColor | UIColor | The textFieldError text Color. This color will appear in the inputTextFiled text based on Card error detector. Default value is nil |
textFieldImage | UIImage | The icon image that is inside the inputTextFiled. This icon will appear in the left or right side of the inputTextFiled based on IconTextFieldPosition value. This property will not be active if the IconTextFieldPosition not specified in the item initializer. |
textFieldKeyboardType | UIKeyboardType | The type of keyboard to display for a given text-based view. Used with the keyboardType property. |
textFieldClearButtonMode | UITextField.ViewMode | Constants that define when overlay views appear in a text field. |
setupView | Func | A card item initializer. |
setCornerRadius | Func | A corner radius properties func. |
setHeaderTitle | Func | A header title label properties func. |
setUnderline | Func | A property to adding a underline in the bottom of the card item. |
setFooterError | Func | A footer error label properties. |
setExpiryDatePicker | Func | Picker view that will be added in Expiry Date inputTextField when the text field becomes the first responder. |
setDefaultStyle | Func | A default style properties setter will be added in the view. |
Corner radius properties:
- radius: The radius is used when drawing rounded corners for the layer’s background, this property is animatable.
- borderWidth: The width of the layer’s border, this property is animatable.
- borderColor: The color of the layer’s border, this property is animatable.
open func setCornerRadius(_ radius: CGFloat, borderWidth: CGFloat? = nil, borderColor: UIColor? = nil)
Header title label properties
- text: The title text.
- fontStyle: default value is nil (use system font 12 pt).
- fontColor: default value is nil (use system color black).
- errorColor: default value is nil (use system color black).
- textAlignment: default value is nil (use NSLeftTextAlignment), this func will add static margins from top 8 pixels and from bottom 4 pixels, and it will not update the frame so we recommend to add minimum 20 pixels to the CardView.
open func setHeaderTitle(_ text: String, fontStyle: UIFont? = nil, fontColor: UIColor? = nil, errorColor: UIColor? = nil, textAlignment: NSTextAlignment? = nil)
Adding an underline in the bottom of the card item:
- defaultColor: The backgroundColor of a underline view, the default value is gray.
- selectedColor: The backgroundColor of a underline view when the cursor is active in the inputTextField, the default value is gray.
open func setUnderline(defaltColor: UIColor? = nil, selectedColor: UIColor? = nil)
Footer error label properties
- text: The error text.
- fontStyle: default value is nil (use system font 10 pt).
- fontColor: default value is nil (use system color red).
- textAlignment: default value is nil (use NSLeftTextAlignment), this func will add static margins from top 4 pixels and from bottom 4 pixels, and it will not update the frame so we recommend to add minimum 14 pixels to the CardView.
open func setFooterError(_ text: String? = nil, fontStyle: UIFont? = nil, fontColor: UIColor? = nil, textAlignment: NSTextAlignment? = nil)
Default Style
A default style contain the following properties:
- inactive: The inactive border style and color.
- focused: The focused border style and color.
- filled: The filled border style and color.
- error: The error border style and color.
open func setDefaultStyle(inactive: ItemBorder? = nil, focused: ItemBorder? = nil, filled: ItemBorder? = nil, error: ItemBorder? = nil)
Picker view that will be added in Expiry Date inputTextField when the text field becomes the first responder
- titleText: The title label of inputAccessoryView
- doneText: The title done button of inputAccessoryView
- cancelText: The title cancel button of inputAccessoryView, if you didn't call this func, the text field displays the standard system keyboard when it becomes first responder. Assigning a custom view to this property causes that view to be presented instead. The Picker contains two columns, first one is all months (1..12) and second one is all available years (current year..current year+20).
open func setExpiryDatePicker(_ titleText: String? = nil, doneText: String? = nil, cancelText: String? = nil)
Delegation
PMCardDelegate
public protocol PMCardDelegate: class {
/**
If any of the items had an error, this func will notify the delegate with the error.
- Parameter cardError: the result of the error, if it's nil that mean there's no error
*/
func allItemsValidation(_ cardError: CardError?)
/**
If the card number had an error, this func will notify the delegate with the error.
- Parameter cardError: the result of the error, if it's nil that mean there's no error
*/
func cardNumberValidation(_ cardError: CardError?)
/**
If the card expiry date had an error, this func will notify the delegate with the error.
- Parameter cardError: the result of the error, if it's nil that mean there's no error
*/
func cardExpiryDateValidation(_ cardError: CardError?)
/**
If the card cvc had an error, this func will notify the delegate with the error.
- Parameter cardError: the result of the error, if it's nil that mean there's no error
*/
func cardCVCNumberValidation(_ cardError: CardError?)
/**
If the card holder name had an error, this func will notify the delegate with the error.
- Parameter cardError: the result of the error, if it's nil that mean there's no error
*/
func cardHolderNameValidation(_ cardError: CardError?)
/**
Passes the Card Number Brand to the delegate.
- Parameter cardBrand: The object carries a credit-card brands (such as Visa and MasterCard)
*/
func cardNumberBrand(_ cardBrand: CardBrand?)
/*
If the back button was clicked, this func will notify the delegate with the event.
- Parameter itemtype: The type of item view
*/
func textFieldDidReturnButtonTapped(_ itemType: ItemType)
/**
Tells the delegate that editing beginned for the specified text field.
- Parameter itemType: The kind of item view
*/
func textFieldDidBeginEditing(_ itemType: ItemType)
/**
Tells the delegate that editing stopped for the specified text field.
- Parameter itemType: The kind of item view
*/
func textFieldDidEndEditing(_ itemType: ItemType)
/**
Tells the delegate that can move from item to item after validate item
- Parameter itemType: The kind of item view
*/
func canMoveToNextItem(currentItem type: ItemType?)
}
PMTokanizeButtonDelegate
extension ViewController: PMTokanizeButtonDelegate {
/**
inform the delegate that the Tokenize Button was clicked.
*/
func tokanizeButtonClicked() { }
/**
inform the delegate that the callback of tokenize request was received.
- Parameter result: the result of the calling tokenize request.
*/
func tokanizeResponseReceived(_ result: Result<Token, MAFPayError>) { }
/**
Tells the delegate that the ThreeDS webView did open
*/
func threeDSWebViewDidOpen()
}
Mirror View
This UI component is built to mirror the input text of card view items.@IBOutlet weak var mirrorView: MirrorView!
mirrorView.setupView(as: .cardNumber)
CVC Hint Button
This UI component is built to add a help button for the CVC field.
@IBOutlet weak var cvcHintButton: CVCHintButton!
RememberCardView
This UIView component is built to enable or disable storing the customer payment card
@IBOutlet weak var rememberCardView: RememberCardView!
RememberCardView Component Options
Option | Type | Description |
---|---|---|
text | String | The text displayed in the component label |
textColor | UIColor | The color of the component label |
fontStyle | UIFont | The font of the component label |
textAlignment | NSTextAlignment | This property use for aligning the text. |
labelSpaceLeft | CGFloat | This property use to change the space between the UISwitch and the label. |
rememberCardSwitch | UISwitch | You can change UISwitch properties from this option |
Interface customization
Option | Type | Description |
---|---|---|
text | String | The text of input textField , default value is empty. It will be replaced if the card item text changed. |
placeholder | String | The placeholder of input textField , the default value is empty. |
textColor | UIColor | The color of the input textField , the default value is a black. |
fontStyle | UIFont | The font of the input textField , the default value is the body style of the system font. |
textAlignment | NSTextAlignment | This property applies to the both the main text string and the placeholder string, the default value of this property is NSLeftTextAlignment. |
View Builder Sample
Sample Code 1
import MAFPay
...
@IBOutlet weak var cardNumberView: CardView!
@IBOutlet weak var holderNameView: CardView!
@IBOutlet weak var cvcNumberView: CardView!
@IBOutlet weak var expiryDateView: CardView!
@IBOutlet weak var submitPaymentButton: TokanizeButton!
override func viewDidLoad() {
super.viewDidLoad()
// setup card views
cardNumberView.setupView(as: .cardNumber)
holderNameView.setupView(as: .holderName)
cvcNumberView.setupView(as: .cvcNumber)
expiryDateView.setupView(as: .expiryDate)
// setup tokenize button
submitPaymentButton.delegate = self
submitPaymentButton.accountHolderID = "A3738qn21"
submitPaymentButton.
verificationType = .rndAmount
}
extension ViewController: PMTokanizeButtonDelegate {
func didTouchUpInTokanizeButton() { }
func didGetTokanizeResponse(_ result: Result<Token, MAFPayError>) { }
func threeDSWebViewDidOpen()
}
Sample Code 2
// Adding header Title
cardNumberView.setHeaderTitle("Card Number", fontStyle: .boldSystemFont(ofSize: 15), fontColor: .darkGray)
holderNameView.setHeaderTitle("holder Name", fontStyle: .boldSystemFont(ofSize: 15), fontColor: .darkGray)
cvcNumberView.setHeaderTitle("CVC Number", fontStyle: .boldSystemFont(ofSize: 15), fontColor: .darkGray)
expiryDateView.setHeaderTitle("Expiry Date", fontStyle: .boldSystemFont(ofSize: 15), fontColor: .darkGray)
// Adding Footer Error
cardNumberView.setFooterError()
holderNameView.setFooterError()
cvcNumberView.setFooterError()
expiryDateView.setFooterError()
// Adding Corner Properties to inputTextField
cardNumberView.setCornerRadius(8, borderWidth: 2, borderColor: .lightGray)
holderNameView.setCornerRadius(8, borderWidth: 2, borderColor: .lightGray)
cvcNumberView.setCornerRadius(8, borderWidth: 2, borderColor: .lightGray)
expiryDateView.setCornerRadius(8, borderWidth: 2, borderColor: .lightGray)
cardNumberView.placeholderText = "0000-0000-0000-0000"
holderNameView.placeholderText = "Your name and surname"
cvcNumberView.placeholderText = "123"
expiryDateView.placeholderText = "Month/Year"
cardNumberView.separatorCharacter = "-"
Sample Code 3
holderNameView.setupView(as: .holderName, iconTextFieldPosition: .left)
cvcNumberView.setupView(as: .cvcNumber, iconTextFieldPosition: .left)
expiryDateView.setupView(as: .expiryDate, iconTextFieldPosition: .left)
cardNumberView.setHeaderTitle("CARD NUMBER", fontStyle: .boldSystemFont(ofSize: 12), fontColor: .darkGray)
holderNameView.setHeaderTitle("CARDHOLDER NAME", fontStyle: .boldSystemFont(ofSize: 12), fontColor: .darkGray)
cvcNumberView.setHeaderTitle("CVC", fontStyle: .boldSystemFont(ofSize: 12), fontColor: .darkGray)
expiryDateView.setHeaderTitle("EXPIRY DATE", fontStyle: .boldSystemFont(ofSize: 12), fontColor: .darkGray)
// Adding Footer Error
cardNumberView.setFooterError()
holderNameView.setFooterError()
cvcNumberView.setFooterError()
expiryDateView.setFooterError()
// Adding Underline to view
cardNumberView.setUnderline(defaltColor: .black, selectedColor: .red)
holderNameView.setUnderline(defaltColor: .black, selectedColor: .red)
cvcNumberView.setUnderline(defaltColor: .black, selectedColor: .red)
expiryDateView.setUnderline(defaltColor: .black, selectedColor: .red)
cardNumberView.placeholderText = "0000 0000 0000 0000"
holderNameView.placeholderText = "Your name and surname"
cvcNumberView.placeholderText = "123"
expiryDateView.placeholderText = "Month/Year"
cardNumberView.textFieldImage = UIImage(named: "cardNumber")
holderNameView.textFieldImage = UIImage(named: "user")
cvcNumberView.textFieldImage = UIImage(named: "look")
expiryDateView.textFieldImage = UIImage(named: "date")
sample code 4
setCardProperty(cardNumberView)
setCardProperty(holderNameView)
setCardProperty(cvcNumberView)
setCardProperty(expiryDateView)
func setCardProperty(_ cardView: CardView) {
cardView.textFieldBackgroundColor = view.backgroundColor
cardView.setCornerRadius(8, borderWidth: 2, borderColor: .white)
cardView.setFooterError()
}
Buy Now Pay Later
MAF Pay provides the ability to offer Buy Now Pay Later (BNPL) providers to your customers with simple UI component integration, you can simply add the BuyNowPayLaterView component to your checkout page and MAF Pay will handle the payment flow for each provider.
Usage
1- Connect the BuyNowPayLaterView from Storyboard with the view controller as below
@IBOutlet weak var buyNowPayLaterView: BuyNowPayLaterView!
2- Setup the BuyNowPayLaterView:
Function parameters:
- checkoutToken : The checkout session token generated by MAF Pay using the Checkout Session API.
- completion : The callback that you define to receive the result object.
- viewController : The ViewController that contains the component
/*
BuyNowPayLaterView setup method
- Parameter checkoutToken
- Parameter completion
- parameter viewController: UIViewController
*/
public func setup(_ checkoutToken: String, viewController: UIViewController, completion: @escaping (CheckoutCallback) -> Void)
CheckoutCallback
MAF Pay provides checkout callback interface to receive the status of the payment transactions.
public enum CheckoutCallback {
case onComplete(BuyNowPayLater)
case onClose(BuyNowPayLater)
case onError(MAFPayError)
}
Sample Code
buyNowPayLaterView.setup("Checkout Token" , viewController: self) { result in
switch result {
case .onComplete(let buyNowPayLater):
print(buyNowPayLater)
case .onClose(let buyNowPayLater):
print(buyNowPayLater)
case .onError(let error):
print(error)
}
}
Customization
MAF Pay BNPL component has been built with minimalistic and user-friendly styles to accommodate most of well-known designs techniques.
To customize the look and feel of BNPL component you can override the component properties to the desired values, the below table list the possible customization properties:
Option | Type | Description |
---|---|---|
isGrouped | bool | A flag used to display the component grouped or expanded. |
borderColor | UIColor | The color to be used on the component borders. |
borderWidth | CGFloat | To specify the border width. |
borderCornerRadius | CGFloat | To set the corners radius. |
mainTitle | String | The text of the BNPL component, the default value is “Buy now pay later”. |
mainTitleTextColor | UIColor | To set the text color of the title. |
mainTitleFont | UIFont | To set the text font of the title. |
paymentOptionTitleTextColor | UIColor | To set the text color of the child BNPL provider options. |
paymentOptionTitleFont | UIFont | To set the text font of the child BNPL provider options. |
tabbyProductsTitleTextColor | UIColor | To set the text color of the child Tabby payment products. |
tabbyProductsTitleFont | UIFont | To set the text font of the child Tabby payment products. |
tabbyDescriptionTitleTextColor | UIColor | To set the text color of Tabby description. |
tabbyDescriptionTitleFont | UIFont | To set the text font of Tabby description. |
tabbyButtonTitleTextColor | UIColor | To set the text color of Tabby provider button. |
tabbyButtonBackground | UIColor | To set the background color of Tabby provider button. |
tabbyButtonTitleFont | UIFont | To set the text font of Tabby provider button. |
mainErrorTitle | String | Set the error title text of the component error messages. |
mainErrorTitleTextColor | UIColor | Set the error title text color of the component error messages. |
mainErrorTitleFont | UIFont | Set the error title text font of the component error messages. |
mainErrorDescriptionText | String | Set the error description text of the component error messages. |
mainErrorDescriptionTextColor | UIColor | Set the error description text color of the component error messages. |
mainErrorDescriptionFont | UIFont | Set the error description text font of the component error messages. |
tabbyErrorTitle | String | Set the error title text of Tabby error messages. |
tabbyErrorTitleTextColor | UIColor | Set the error title text color of Tabby error messages. |
tabbyErrorTitleFont | UIFont | Set the error title text font of Tabby error messages. |
tabbyErrorDescriptionText | String | Set the error description text of Tabby error messages. |
tabbyErrorDescriptionTextColor | UIColor | Set the error description text color of Tabby error messages. |
tabbyErrorDescriptioneFont | UIFont | Set the error description text font of Tabby error messages. |
spotiiErrorTitle | String | Set the error title text of Spotii error messages. |
spotiiErrorTitleTextColor | UIColor | Set the error title text color of Spotii error messages. |
spotiiErrorTitleFont | UIFont | Set the error title text font of Spotii error messages. |
spotiiErrorDescriptionText | String | Set the error description text of Spotii error messages. |
spotiiErrorDescriptionTextColor | UIColor | Set the error description text color of Spotii error messages. |
spotiiErrorDescriptionFont | UIFont | Set the error description text font of Spotii error messages. |
tamaraProductsTitleTextColor | UIColor | Set the text color of the child Tamara payment products.. |
tamaraProductsTitleFont | UIFont | Set the text font of the child Tamara payment products. |
tamaraDescriptionTitleTextColor | UIColor | Set the text color of Tamara description. |
tamaraDescriptionTitleTextColor | UIColor | Set the text color of Tamara description. |
tamaraDescriptionTitleFont | UIFont | Set the text font of Tamara description. |
tamaraButtonTitleTextColor | UIColor | Set the text color of Tamara provider button. |
tamaraButtonBackground | UIColor | Set the background color of Tamara provider button. |
tamaraButtonTitleFont | UIFont | Set the text font of Tamara provider button. |
tamaraErrorTitle | String | Set the error title text of Tamara error messages. |
tamaraErrorTitleTextColor | UIColor | Set the error title text color of Tamara error messages. |
hideTileView | Bool | A flag used to hide the title view. |
Sample Code
The below code customize the look and feel of the BNPL component.
buyNowPayLaterView.isGrouped = false
buyNowPayLaterView.borderColor = .red
buyNowPayLaterView.borderWidth = 1
buyNowPayLaterView.borderCornerRadius = 2
buyNowPayLaterView.mainTitle = "Buy now pay later with new text"
buyNowPayLaterView.mainTitleTextColor = .green
buyNowPayLaterView.mainTitleFont = UIFont.systemFont(ofSize: 15, weight: .bold)
buyNowPayLaterView.paymentOptionTitleTextColor = .green
buyNowPayLaterView.paymentOptionTitleFont = UIFont.systemFont(ofSize: 15, weight: .bold)
buyNowPayLaterView.paymentOptionTitleTextColor = .green
buyNowPayLaterView.paymentOptionTitleFont = UIFont.systemFont(ofSize: 15, weight: .bold)
buyNowPayLaterView.mainErrorTitle = "MAIN ERROR TITLE CHANGED"
buyNowPayLaterView.mainErrorTitleTextColor = .red
buyNowPayLaterView.mainErrorTitleFont = .boldSystemFont(ofSize: 14)
buyNowPayLaterView.mainErrorDescriptionText = "MAIN ERROR DESC. CHANGED"
buyNowPayLaterView.mainErrorDescriptionTextColor = .green
buyNowPayLaterView.mainErrorDescriptioneFont = .italicSystemFont(ofSize: 20)
Tabby Promo Messages
You can implement the snippets from your end using the following links for the pop-up (can be also opened in WebView). We do recommend using the PDP/Cart snippets, with the 'i' button as on the Front-end side. Pop-up URLs for checkout page, payment methods:
- https://checkout.tabby.ai/promos/product-page/installments/en/
- https://checkout.tabby.ai/promos/product-page/installments/ar/
Apple Pay
Setup Apple Pay
You have to enable Apple Pay in your project with Xcode as follows:
- Add the Apple Pay capability to your app. By following the steps below:
- Open your project settings.
- Choose the Signing & Capabilities tab.
- Add the Apple Pay capability.
- You may be prompted to log in to your developer account at this point.
- Enable the checkbox next to the merchant ID you created earlier, and your app is ready to accept Apple Pay.
Usage
a. Add the delegate MAFApplePayDelegate.
public protocol MAFApplePayDelegate: class {
/**
Informs the delegate that Presenting PKPaymentAuthorizationViewController Failed.
- parameter error: has two cases: unableToPresentApplePay and cannotMakePayments
*/
func applePayDidFailed(with error: MAFPayError)
/**
Informs the delegate that payment authorization finished.
- parameter controller: The payment authorization view controller.
*/
func paymentAuthorizationViewControllerDidFinish(_ controller: PKPaymentAuthorizationViewController)
/**
Informs the delegate that the user has authorized the payment request and asks for a result.
- parameter controller: The payment authorization view controller.
- parameter payment: it has all important wallet date: walletData, walletHeader, walletSignature and walletVersion
*/
func paymentAuthorizationViewController(_ controller: PKPaymentAuthorizationViewController, didAuthorizePayment payment: ApplePayPayment, handler completion: @escaping (PKPaymentAuthorizationResult) -> Void)
/**
Informs the delegate that the user is authorizing the payment request.
- parameter controller: The payment authorization view controller.
*/
func paymentAuthorizationViewControllerWillAuthorizePayment(_ controller: PKPaymentAuthorizationViewController)
/**
Informs the delegate that the user selected a shipping method and asks for an updated payment request.
*/
func paymentAuthorizationViewController(_ controller: PKPaymentAuthorizationViewController, didSelect shippingMethod: PKShippingMethod, handler completion: @escaping (PKPaymentRequestShippingMethodUpdate) -> Void)
/**
Informs the delegate that the user selected a shipping address and asks for an updated payment request.
*/
func paymentAuthorizationViewController(_ controller: PKPaymentAuthorizationViewController, didSelectShippingContact contact: PKContact, handler completion: @escaping (PKPaymentRequestShippingContactUpdate) -> Void)
}
You can retrieve Apple Pay payment token data through the function paymentAuthorizationViewController, the payment object contains the required four parameters that you need to pass in the server-to-server payment request, these parameters are:
- walletData
- walletHeader
- walletSignature
- walletVersion
func paymentAuthorizationViewController(_ controller: PKPaymentAuthorizationViewController, didAuthorizePayment payment: ApplePayPayment,
handler completion: @escaping (PKPaymentAuthorizationResult) -> Void)
b. Add iOS Library PassKit. To Apple pay implementation
import PassKit
c. Add public instance for object MAFApplePay.
var applePay: MAFApplePay!
d. (Optional) Make paymentRequest object using createPaymentRequest function in MAFApplePay.
let paymentRequest = MAFApplePay.createPaymentRequest(with: "Merchant ID", country: "", currency: "")
paymentRequest.paymentSummaryItems = [
"Add your Payment Summary Items"
]
Note: paymentRequest extend from PKPaymentRequest so you can add paymentSummaryItems or other public variables.
Sample Apple Pay Button
@IBAction func applePayButtonTapped(_ sender: Any) {
let paymentRequest = MAFApplePay.createPaymentRequest(with: "Merchant ID", country: "", currency: "")
paymentRequest.paymentSummaryItems = [
"Add your Payment Summary Items"
]
applePay = MAFApplePay(with: <#T##MAFApplePayDelegate#>)
applePay.presentApplePayViewController(on: <#T##UIViewController#>, with: <#T##PKPaymentRequest#>)
}
MAF Pay SDK Operations
Tokenize Card
Tokenize card is a process for storing the card sensitive data in MAF Pay’s secure and PCI compliant system and replace this data with a unique token that refers to the stored data.
Function parameters:
- verify: An optional value to make verify card after Tokenize.
- card: The card details such as card number, expiry, cvc.
- accountHolderId: An optional value, used to link the card to an existing user.
- completion: the tokenize process callback which contains the result or MAFPayError objects.
public static func tokenize(with verifyType: VerifyType = .none, card: Card, accountHolderId: String? = nil, viewController: UIViewController? = nil, completion: @escaping MAFPayResponse<Token>)
Get card List
You can use this operation to retrieve all card tokens “Token” for a specific customer “AccountHolderId”.
Function parameters:
- completion: is a callback that you define to receive the result object.
func getCardList(completion: @escaping MAFPayResponse<[Token]>)
Delete Card You can use this operation to delete a specific card token.
Function parameters:
- completion: is a callback that you define to receive the result object.
- cardToken: the card alias name, that has been assigned to a specific user card.
func deleteCard(by cardToken: String, completion: @escaping MAFPayResponse<Void>)
Confirm Verification
You can use this operation to complete the verification process, the user provides the verification amount. You will pass the verification amount and cardToken as part of confirm verification. MAF Pay checks if the amounts match then card status is set to verified.
Function parameters:
- completion: is a callback that you define to receive the result object.
- amount: the amount value that the customer entered.
- cardToken: the card alias name, that has been assigned to a specific user card.
func confirmVerification(by amount: String, cardToken: String, completion: @escaping MAFPayResponse<Void>)
Set card as default
You can use this operation to set card as default to a specific card token.
Function parameters:
- cardToken: the card alias name, that has been assigned to a specific user card.
- accountHolderId: The account holder ID that been created for the customer.
- completion: is a callback that you define to receive the result object.
func setCardAsDefault(by cardToken: String, accountHolderId: String? = nil, completion: @escaping MAFPayResponse<Void>)
Processing 3D Secure 2
Once submitting a payment transaction MAF Pay will start the process of authenticating the card holder using 3D Secure 2 and it will generate a unique 3DS authentication reference “threeDsAuthId” that will be used to complete the 3DS flow.
Function parameters:
- threeDsAuthId: A unique reference for the 3D Secure authentication generated by the gateway, this parameter used to complete the 3D Secure 2 authentication.
- viewController: The current viewController.
public static func processThreeDSAuth(with threeDsAuthId: String, viewController: UIViewController, completion: @escaping MAFPayResponse<[String: Any]>)
Sample code
MAFPay.processThreeDSAuth(with: "threeDsAuthId", viewController: self) { [weak self] result in
switch result {
case .success(let response):
print("--response-==->\(response)")
case .failure(let error):
print("--error-==->\(error)")
}
}
Bank Transfer
This payment method allows merchants to accept bank transfer payments for the services/goods they provide to their customers. Bank transfer payment method available using same integration you use in checkout session.
Link Bank Account
In order for your customer to be able to make payment using bank transfer, first they need to authorise their bank to transfer funds from their account to your account. This is known in their bank account as a 'Beneficiary'. For some banks, creating a beneficiary can have a cool-down period of up to 24 hours.
- accountHolderId: The account holder ID that been created for the customer.
- bankToken: The banks alias name, that has been assigned to a specific user bank.
- viewController: The current viewController.
- completion: A callback contained bankToken in success case and MAFPayError in failure case.
func linkBank(with accountHolderId: String?, bankToken: String? = nil, viewController: UIViewController, completion: @escaping LinkBankResponse<String>)
Sample code
MAFPay.linkBank(with: "", bankToken: "", viewController: self) { result in
switch result {
case .onComplete(let token):
print(token)
case .onClose:
print("onClose")
case .onError(let err):
print(err)
}
}
Get Account Holder Banks
This operation allows merchants to retrieve all banks related to specific accountHolder from MAF Pay.
- completion: is a callback that you define to receive the result object.
func getAccountHolderBanks(_ completion: @escaping MAFPayResponse<[Bank]>)
Sample code
MAFPay.getAccountHolderBanks { result in
switch result {
case .success(let banks):
print(banks)
case .failure(let error):
print(error)
}
}
Pay With Bank Account
In this step, the customer will confirm the amount they want to transfer from their account to your account. MAF Pay provides bank transfer payment through checkout session component. Once payment initiation has been completed, you will receive the final payment status on your feedback URL configured on MAF Pay portal.
- checkoutToken: The checkout session token which is required to complete the payment.
- bankToken: The banks alias name, that has been assigned to a specific user bank.
- viewController: The current viewController.
- completion: A callback contained in complete case and MAFPayError in failure case.
func bankTransfer(with checkoutToken: String, bankToken: String, viewController: UIViewController, completion: PayBankingResponse)
Sample code
MAFPay.bankTransfer(with: "checkoutToken", bankToken: "bankToken", viewController: self) { result in
switch result {
case .onComplete():
print(onComplete)
case .onClose:
print("onClose")
case .onError(let err):
print(err)
}
}
Binance Pay
Binance Pay is a contactless, borderless and secure cryptocurrency payment technology designed by Binance. Binance Pay allows Binance customer to pay and get paid in crypto from your friends and family worldwide.
Setup
a. You need to add URL Scheme from app project settings -> info -> Url types.
b. Add the following key to the plist file:
<key>LSApplicationQueriesSchemes</key>
<array>
<string>com.binance.app.binance</string>
<string>com.binance.pay.support</string>
</array>
c. Open the AppDelegate class and add the following code:
import MAFPay
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
MAFPay.handleBinance(openURL: url)
}
How to use
After setting up Binance Pay you are ready to add Binance Pay by using one of the following integration options that MAF Pay provides:
1- MAFPay operation function:
In this integration, you are responsible for creating and maintaining the Binance Pay button on your checkout screen, and you can initiate Binance Pay transaction processing using the function below:
- checkoutToken: The checkout session token which is required to complete the payment.
- redirectScheme: The custom URL scheme link
- containerView: The superview of all other views
- completion: A callback does not contained any Result object in success case and MAFPayError in failure case
func payWithBinanceWallet(with checkoutToken: String, redirectScheme: String, containerView: UIView, completion: @escaping BinanceResult)
2- Binance Pay Component
MAF Pay provides a Binance Pay button as a component that you can add to your checkout screen and MAF Pay will handle the interaction with the button and return the appropriate response in delegate:
Usage
@IBOutlet weak var binanceButton: BinancePayButton!
binanceButton.delegate = self
binanceButton.redirectScheme = "url://"
binanceButton.setDefaultStyle()
binanceButton.checkoutToken = "checkoutToken"
protocol BinanceButtonDelegate: AnyObject {
/// Tells the delegate that the Binance Button tapped.
func binanceButtonClicked()
/// Tells the delegate that the Binance Button Activated.
func binanceButtonActivated()
/**
Tells the delegate that the callback of Checkout Process.
- Parameter result: the result of the calling Binance.
*/
func payWithBinanceResponse(_ result: BinanceResult)
}
MAF Pay SDK Objects
Response Token Object
The token object contains the result of the tokenization request, the values that the token object are:
a. cardToken: The card alias name, that has been assigned to a specific user card.
b. card: the card object holds the details of the tokenized card, the values that the card holds are:
i. cardBrand: such as VISA, MasterCard
ii. cardType: such as Credit, Debit
iii. cardBin: the bank identification number (BIN) is the first six digits of the card number.
iv. cardMaskedNumber: the masked card number. For example, 400555XXXXXX0019
v. expiryMonth: the card expiry month.
vi. expiryYear: the card expiry year.
vii. cardHolderName: the customer name on the credit card.
viii. status: the status of the card verification.
c. accountHolderId: The account holder ID that the card token is linked to.
struct Token {
let cardToken: String
let accountHolderId: String?
let card: Card
struct Card {
let cardBrand: String
let cardType: String
let cardBin: String
let cardMaskedNumber: String
let expiryMonth: String
let expiryYear: String
let cardHolderName: String?
let status: String?
}
Response BuyNowPayLater Object
The BuyNowPayLater object contains the result of the Buy Now Pay Later checkout request. the values that BuyNowPayLater object have are:
- checkoutToken : the checkoutToken that have been used for the checkout process
public struct BuyNowPayLater: Codable {
let checkoutToken: String
}
Bank Object
The Bank object contains the result of the bank information. the values that Bank object have are:
- bankToken: The bank token
- status: The status
- bankName: The bank name
- bankCountry: The bank country
- bankLogo: The bank logo
public struct Bank: Codable {
public let bankToken: String?
public let status: String?
public let bankName: String?
public let bankCountry: String?
public let bankLogo: String?
}
MAF Pay SDK Errors
MAF Pay Error
MAFPayError Enum returns errors whenever errors occur while initiating calls to MAF Pay backend system. The object contains the following fields:
- errorDescription: It returns description for error.
- errorCode: It returns error code for error.
- extraParams: It returns a dictionary that contains parameters that help to identify the error reason.
case noInternet = dynamic value
case timeOut = dynamic value
case serverError = dynamic value
case internalError = dynamic value
Case | errorCode | errorDescription |
---|---|---|
noInternet | 5003 | Missing authentication data |
timeOut | 5001 | Missing identifier data |
serverError | Please refer to Server Errors | |
internalError | Please refer to section Internal Error below |
Internal Error
InternalError Enum returns errors whenever SDK setup values validation fails. The object contains the following fields:
- errorDescription: It returns description for error.
- errorCode: It returns error code for error.
Case | errorCode | errorDescription |
---|---|---|
missingAuthenticationData | 9000 | Missing authentication data |
missingIdentifierData | 9001 | Missing identifier data |
missingAuthentication | 9002 | Missing authentication key |
allIdentifierFilled | 9003 | One of the merchant-id or partner-id must be field not both |
invalidAccessToCameraError | 9004 | The camera permission is needed to scan the card |
unableToPresentApplePay | 9005 | Unable to present Apple Pay authorization |
cannotMakePayments | 9006 | Can't Make Payments |
cannotParsePKPayment | 9007 | Can't Parse PKPayment Object |
tabbySessionIdIsEmpty | 9008 | Tabby session ID is empty |
tabbyIdIsEmpty | 9009 | Tabby ID is empty |
certificateNotMatched | 9014 | Certificate does not match, please contact your support team |
missingCheckoutToken | 9023 | Checkout token is missing |
missingBankToken | 9024 | Bank token is missing |
missingBinancePayRedirectScheme | 9025 | Redirect Scheme is missing |
binancePayNotSupported | 9026 | Binance Pay not supported |
Card Error
CardError Enum returns errors whenever Card values validation fails. The object contains the following fields:- errorDescription: It returns description for error.
- errorCode: It returns error code for error.
Case | Code | Description |
---|---|---|
invalidCardNumberLengthError | 3000 | Wrong card number length |
invalidCardNumberError | 3001 | Invalid card number |
invalidCVCLengthError | 3002 | Invalid CVC length |
invalidCVCFormatError | 3003 | Invalid CVC format |
invalidExpiryMonthError | 3004 | Invalid expiry month |
invalidExpiryYearError | 3005 | Invalid expiry year |
invalidExpiryDateError | 3006 | Invalid expiry date |
invalidCardHolderNameError | 3007 | Invalid card holder name |
unsupportedCardError | 3008 | Invalid card holder name |
cardNumberIsEmptyError | 3009 | Card number is empty |
cvcIsEmptyError | 3010 | CVC is empty |
expiryDateIsEmptyError | 3011 | Expiry date is empty |
missingCardNumberError | 5000 | Missing card number view |
missingCVCNumberError | 5001 | Missing CVC number view |
missingExpiryDateError | 5002 | Missing expiry date view |
tabbySessionIdIsEmpty | 9008 | Tabby session ID is empty |
tabbyIdIsEmpty | 9009 | Tabby ID is empty |
Customizing CardView error
switch cardError {
case .invalidCardNumber, .invalidCardNumberLength:
cardNumberView.errorText = "Card number error"
default: break
}
Android SDK
Requirements
The MAF Pay Android SDK requires Java 8 and is compatible with apps targeting API level 19 or above.
Getting Started
Installation
Gradle
In your build.gradle file of app module, add below dependency to import this library:
dependencies {
implementation ('com.majidalfuttaim:mafpay:1.9.0:release@aar'){ transitive = true}
}
Maven
Add the below code inside your root build file.
repositories {
maven { url "https://repo.mafpayments.com" }
maven { url 'https://jitpack.io'}
maven {
url "https://cardinalcommerceprod.jfrog.io/artifactory/android"
credentials {
username 'cybersource_beamportal'
password 'AKCp8k7ugpeH194bHXzzrEj7k51p7n64arfcgCk6Nb7SRt7BucLZXaFQm63rotKr7W2UsLTbY'
}
}
}
Setup the SDK
In order to initialize the SDK you should use MafPay.init() function in your application Class or make any activity/Fragment where you want to implement payment integration.
Java
public class MainActivity extends AppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
MafPaySdkConfiguration sdkConfiguration = new MafPaySdkConfiguration.Builder().
withEnvironment(Environment.SANDBOX)
.withMerchantId("MerchantID")
.withApiKey("API-Key")
.build();
MafPay.init(sdkConfiguration, true);
- JWT token of the authentication provider, for now we only support Auth0 authentication management system
MafPay.setAuthorization("<JWT Token Value>");
}
}
Kotlin
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
val sdkConfiguration: MafPaySdkConfiguration =
MafPaySdkConfiguration.Builder().
withEnvironment(Environment.SANDBOX)
.withMerchantId("MerchantID")
.withApiKey("API-Key")
.build()
MafPay.init(sdkConfiguration, true)
- JWT token of the authentication provider, for now we only support Auth0 authentication management system
MafPay.setAuthorization("<JWT Token Value>")
}
}
Setup the environment
To setup the required environment you can use Environment parameter. Environment is as enum returns all supported languages in the SDK. The object contains the following cases:
public enum Environment {
SANDBOX,
PRODUCTION
}
Setup the language
To setup the required language you can use language parameter. MAFPayLanguage is as enum returns all supported languages in the SDK. The object contains the following cases:
enum class MafPayLanguage {
ARABIC, ENGLISH;
}
Example:
MafPay.setLanguage(MafPayLanguage.ENGLISH)
MafPay.setLanguage(MafPayLanguage.ARABIC)
Required permissions
Add the following code into your AndroidManifest file:
<uses-permission android:name="android.permission.INTERNET" />
Debug mode
A Boolean value determining the SDK logs all errors. Debug mode is optional.
Java
boolean enableLogging=true;
MafPay.init(sdkConfiguration, enableLogging);
Kotlin
val enableLogging = true
MafPay.init(sdkConfiguration, enableLogging)
Callback<T>
An interface in order to get results for async operations.
MAF Pay Card Components
MAF Pay components are UI components that securely collects your customers payment card details. There are two ways to use the requested components either XML layout or Java code.
Components Items
- CardNumberView: the view that is responsible for collecting cards numbers.
- cvcNumberView: the view that is responsible for collecting the card security code.
- expiryDateView: the view that is responsible for collecting the card expiry date
- CardHolderNameView: the view that is responsible for collecting card holder name.
- TokenizeButton: is the button that used to submit the payment form data, if the form data are not valid it will cancel the submission and returns the errors.
- MirrorView: these UI components are built to mirror the input text of card view items.
- CvvHintView : this UI component used to show a CVC hint as a popup message.
- RememberMeCheckBox : this UI component is built to enable or disable storing the customer payment card.
Components Setup
Setup using XML// Example 1. CardNumberView
<com.majidalfuttaim.mafpay.views.CardNumberView
android:id="@+id/edtCardNumber"
..../>
// Example 2. CardCvvView
<com.majidalfuttaim.mafpay.views.cvcNumberView
android:id="@+id/edtCvvNumber"
..../>
// Example 3. CardDateView
<com.majidalfuttaim.mafpay.views.expiryDateView
android:id="@+id/edtCardDateView"
..../>
// Example 4. CardHolderNameView
<com.majidalfuttaim.mafpay.views.CardHolderNameView
android:id="@+id/edtCardHolderNameView"
..../>
// Example 5. RememberMeCheckBox
<com.majidalfuttaim.mafpay.views.RememberMeCheckBox
android:id="@+id/rememberMeSwitch"
..../>
<com.majidalfuttaim.mafpay.views.TokenizeButton
android:id="@+id/btnToknaize"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_gravity="center"
android:background="@color/blue_dark"
android:gravity="center"
android:text="Submit"
android:textAllCaps="false"
android:textColor="@color/white" />
Setup using Java code
public class ComponentsFragment extends Fragment{
private CardNumberView etCardNumber;
public void onViewCreated(View view, Bundle savedInstanceState) {
super.onViewCreated(view, savedInstanceState);
MafPaySdkConfiguration sdkConfiguration = new MafPaySdkConfiguration.Builder().
withEnvironment(Environment.SANDBOX)
.withMerchantId("MerchantID")
.withApiKey("API-Key")
.build();
MafPay.init(sdkConfiguration, true);
etCardNumber = view.findViewById(R.id.edtCardNumber);
etCardNumber.setOnPaymentCardEventListener(new OnPaymentCardEventListener() {
@Override
public void isValid()
}
@Override
public void onError(CardError cardError) {
}
});
Setup using Kotlin code
class ComponentsFragments : Fragment() {
private lateinit var etCardNumber: CardNumberView
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
super.onViewCreated(view, savedInstanceState)
val sdkConfiguration: MafPaySdkConfiguration =
MafPaySdkConfiguration.Builder().withEnvironment(Environment.SANDBOX)
.withMerchantId("MerchantID")
.withApiKey("API-Key")
.build()
MafPay.init(sdkConfiguration, true)
etCardNumber = view.findViewById(R.id.edtCardNumber)
// You can get Event Listener for each components.
etCardNumber.setOnPaymentCardEventListener(object : OnPaymentCardEventListener {
override fun isValid() {
}
override fun onError(cardError: CardError?) {
}
})
Card verification setup
TokenizeButton contains a setup function “setUp”, that contains an optional parameter called “verificationType” below is description of the flow based on the parameter value :
- No Verification: If the property value is set to “none” which is the default property value, MAF Pay will ONLY tokenize the card.
- 3DS Authentication: If the property value is “threeDs”, the card 3DS enrolment is checked, if the card is enrolled MAF Pay will redirect the user to the issuer page for authentication. If the 3DS check fails or the 3DS authentication fails MAF Pay will not tokenize the card.
- Random Amount deduction: If the property value is “rndAmount”, MAF Pay will tokenize the card, deduct a random amount from the card. You can pass the value of cardToken in the confirmVerification operation to verify the card.
//Setup method values are optional
btnToknaize.setUp("AccountHolderId", VerifyType.ThreeDs)
//Getting the Result
btnToknaize.getResult().observe(getViewLifecycleOwner(), result -> {
MafResult<Token> mafResultEvent = result.getContentIfNotHandled();
if (mafResultEvent instanceof MafResult.Success) {
handleSuccess((MafResult.Success<Token>) mafResultEvent);
} else if (mafResultEvent instanceof MafResult.Failure) {
handleFailure((MafResult.Failure) mafResultEvent);
} else if (mafResultEvent instanceof MafResult.Loading) {
startLoading();
}
}
);
Set card as default
TokenizeButton contains a property “isDefaultCard” which takes a Boolean value to indicate whether the card will be the default card.
btnToknaize.isDefaultCard = true
Set card for recurring
TokenizeButton contains a property “isRecurring” which takes a Boolean value to indicate whether the card will be used in processing recurring transactions
Note: you have to send verifyCard = .threeDs3ds along with isRecurring=true parameters
btnToknaize.isRecurring = true
Card verification setup (Deprecated)
To enable card verification you can send an optional parameter in the tokenize button setup.
btnToknaize.setUp(new OperationCallBack<Token>() {
@Override
public void startLoading() {
}
@Override
public void onSuccess(Token result) {
}
@Override
public void onError( MafPayError error) {
}
},"AccountHolderId",true);
Mirror View
To use the MirrorView, add a Card Element view and MirrorView to your XML layout as below:
<com.majidalfuttaim.mafpay.views.MirrorView
android:id="@+id/etCardNumberMirror"
android:layout_width="match_parent"
android:layout_height="wrap_content"
app:componentSharedType="cardNumber"
/>
<com.majidalfuttaim.mafpay.views.CardNumberView
android:id="@+id/edtCardNumber"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginStart="10dp"
android:layout_marginEnd="10dp"
app:disableErrorMessage="true"
app:gravity="start"
app:gravityIconLogo="start"
app:hintText="0000 0000 0000"
app:showErrorWhileTyping="true"
app:titleTextEnable="true" />
Also you need to use the below Java code :
CardNumberView etCardNumber = view.findViewById(R.id.edtCardNumber);
MirrorView etCardNumberMirror = view.findViewById(R.id.etCardNumberMirror);
etCardNumberMirror.addMirrorElement(etCardNumber);
CvvHint View
To use the CVVHintView, add the component to your XML layout as below :
<com.majidalfuttaim.mafpay.views.CvvHintView
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:background="@android:color/transparent"
android:textColor="@color/blue_light"
android:text="@string/title_text_cvv_hint" />
For text customization you can override the default message by using the below example :
<string name="fragment_cvvhint_title">CVV or CVC</string>
<string name="fragment_cvvhint_msg">The CVV/CVC code on a credit card is a 3-4 digit numbers, please copy your card code from the back of your Visa/ Master card or from front side of American Express and continue with your payment.</string>
View Component Options and Methods
Field element | Relevant attributes/methods | Type | Description |
---|---|---|---|
Label Hint Text | app:hintText x.setTextHint("") | string | Set hint text label of the component. |
Label Hint Text Color | app:hintTextColor x.setHintTextColor(color) | color | To change your hint text color ex. Color.Red, Color.Green, Color.Black ..etc, |
Label Error text size | app:errorTextSize x.setErrorTextSize(value) | dimension | To make your font size error smaller, Normal, Large, or Huge. |
Label Error text color | app:errorTextColor x.setErrorTextColor(color) | reference.color | To change your error text color ex. Color.Red, Color.Green, Color.Black ..etc, |
Label Error text title | app:errorTextTitle x.setErrorTextTitle("") | string | Set error text label of the component. |
Disable Error message | app:disableErrorMessage x.disableErrorMessage(value) | boolean | To hide or show the error label message view use boolean type ex. true. |
Error while typing | app:showErrorWhileTyping x.showErrorWhileTyping() | boolean | A View's visibility status of the error while typing ,which tells the app user that the component have error while typing. |
Label Error field text color | app:textFieldErrorTextColor setTextFiledColorErrorActive() | reference.color | To change your error text color while typing ex. Color.Red, Color.Green, Color.Black ..etc, |
Label text color | app:textColor x.setTextColor() | reference.color | To make your font ex. color Color.Red, Color.Green, Color.Black ..etc, |
Label text size | app:textSize x.setTextSize() | dimension | To make your font size error smaller, Normal, Large, or Huge. |
Label Cursor field drawable | app:textCursorDrawable x.setTextCursorDrawable() | reference.color | EditText cursor is the blinking slim vertical line display inside EditText, which tells the app user that EditText is now selected and you can write your text here. |
The divider between text input | app:divider_formatter x.setDivider() | string | Add space between the element, This property is limited only to the Card number and Expiry date. ex CardDateView.setDivider("/") --> 02/22 |
Background for the component | app:cardBackgroundElement x.setEditTextBackground() | reference | Set the background element to a given Drawable, or remove the background using @null. |
Font type from assets folder | app:fontType x.setTypeface() | string | Set typeface font for all views (title, default text, error). ex. x.setTypeface("sans-serif") |
Label title text size | app:titleTextSize x.setTitleTextSize() | dimension | To make your font size smaller , Normal, Larger, or Huge. |
Label title text color | app:titleTextColor x.setTitleTextColor() | reference.color | To change title text color ex. Color.Red, Color.Green, Color.Black ..etc, |
Label title text | app:titleText x.setTitleText() | string | To change title text ex. "Card number" |
Label title text visible | app:titleTextEnable x.isTitleTextEnabled() | boolean | A View's visibility status is of boolean type and can have one of two options true of false. |
Element height inside the component | app:setElementHeightEd x.setHeightEditElement() | dimension | An integer number appended with a unit such as "14dp". |
Element gravity status | app:gravity x.setGravityElement() | int | A View's gravity status is of int type and can have one of many options:Gravity.End ,Gravity.Start,Gravity.Left,Gravity.Center ...etc. |
Label title text gravity | app:titleTextGravity x.setTitleGravity() | int | A View's gravity status is of int type and can have one of many options:Gravity.End ,Gravity.Start,Gravity.Left,Gravity.Center ...etc. |
Label error text gravity | app:errorTextGravity x.setErrorTextGravity() | int | A View's gravity status is of int type and can have one of many options:Gravity.End ,Gravity.Start,Gravity.Left,Gravity.Center ...etc. |
Icon logo component | app:editTextImage x.setEditTextImage() | drawable | Set Icon drawable for the component |
Icon gravity logo | app:gravityIconLogo x.setEditTextImageGravity() | int | A View's gravity status is of int type. |
imeOptions | app:imeOptions x.setImeOptions() | boolean | Change the editor type integer associated with the text view, which is reported to an Input Method Editor (IME) with {@link EditorInfo#imeOptions}'actionNext','actionPrevious' |
Enable DatePicker dialog | app:dateFromPickerDialog x.setDatePickerDialog() | boolean | To enable/disable select date from DatePicker dialog on ExpireDate component. |
Enable Title Animation | app:enableTitleAnimation="true" x.isTitleAnimationEnabled(true) | boolean | To simulate the material design animation for the component title. |
MirrorView Component Options and Methods
Field element | Relevant attributes/methods | Type | Description |
---|---|---|---|
Label title text size | app:titleTextSize x.setTitleTextSize() | dimension | To make the app font size smaller , Normal, Larger, or Huge. |
Label title text color | app:titleColor x.setTitleTextColor() | reference.color | To change the title text color for example: Color.Red, Color.Green, Color.Black ... etc. |
Label title text gravity | app:titleGravity x.setTitleGravity() | int | A Views gravity status is of int type and can have one of many options: Gravity.End , Gravity.Start, Gravity.Left, Gravity.Center... etc. |
Background for the component | app:backgroundElement x.setBackgroundElement() | reference | Set the background element to a given Drawable |
Label title text color | app:titleColor x.setTitleTextColor() | reference.color | To change title text color for example: Color.Red, Color.Green, Color.Black … etc. |
DatePickerDialog option in the expiry date view:
<com.majidalfuttaim.mafpay.views.ExpiryDateView
....
app:hintText="MM/YY"
app:dateFromPickerDialog="true"
/>
Customizing the error label:
<com.majidalfuttaim.mafpay.views.ExpiryDateView
....
app:errorTextTitle="@string/txt_error_label"
app:errorTextColor="@color/blue_light"
app:errorTextGravity="center|start"
app:errorTextSize="@dimen/textSize_14"
app:disableErrorMessage="false"
/>
Adding Icon logo for a component and icon gravity to prompt a user for specific input, also you can set multiple gravityType attributes if needed (separated by '|') with:
<com.majidalfuttaim.mafpay.views.CardNumberView
....
app:gravityIconLogo="center|end"
app:editTextImage="@drawable/ic_card_default"
/>
Setting the background of the component:
<com.majidalfuttaim.mafpay.views.CardNumberView
....
app:cardBackgroundElement="@drawable/gradient_white_border"
/>
MAF Pay Material Card Components
MAF Pay components are UI components that securely collects your customers payment card details. There are two ways to use the requested components either XML layout or Java code.
Components Items
- MaterialCardNumberView: the view that is responsible for collecting cards numbers.
- MaterialCardCvcView: the view that is responsible for collecting the card security code.
- MaterialCardExpiryView: the view that is responsible for collecting the card expiry date
- MaterialCardHolderView: the view that is responsible for collecting card holder name.
- TokenizeButton: is the button that used to submit the payment form data, if the form data are not valid it will cancel the submission and returns the errors.
- MirrorView: these UI components are built to mirror the input text of card view items.
- CvvHintView : this UI component used to show a CVC hint as a popup message.
- RememberMeCheckBox : this UI component is built to enable or disable storing the customer payment card.
Setup using XML
<com.majidalfuttaim.mafpay.views.material.MaterialCardNumberView
android:id="@+id/edtCardNumber"
android:layout_width="match_parent"
android:layout_height="wrap_content" />
<com.majidalfuttaim.mafpay.views.material.MaterialCardExpiryView
android:id="@+id/edCardMonthYear"
android:layout_width="match_parent"
android:layout_height="wrap_content" />
<com.majidalfuttaim.mafpay.views.material.MaterialCardCvcView
android:id="@+id/edtCvvNumber"
android:layout_width="match_parent"
android:layout_height="wrap_content" />
<com.majidalfuttaim.mafpay.views.material.MaterialCardHolderView
android:id="@+id/edCardName"
android:layout_width="match_parent"
android:layout_height="wrap_content" />
<com.majidalfuttaim.mafpay.views.TokenizeButton
android:id="@+id/btnToknaize"
android:layout_width="match_parent"
android:layout_height="wrap_content"
app:enableDefaultStyle="true" />
Material Customization
Since Material Components (Material Design Based) Merchants The Default Theme is Outline Merchant can customize Components through Style.Xml by override Material Styles . Merchant can use all attributes exist in Material Design Input Layout for more information refer to # Material Text fields
<style name="Maf.CardNumberInputLayoutStyle" parent="MafInputLayoutStyle">
</style>
<style name="Maf.CardCvcInputLayoutStyle" parent="MafInputLayoutStyle">
</style>
<style name="Maf.CardExpiryInputLayoutStyle" parent="MafInputLayoutStyle"></style>
<style name="Maf.CardHolderNameInputLayoutStyle" parent="MafInputLayoutStyle"></style>
Examples :
Making Material theme Filled Box
<style name="Maf.CardNumberInputLayoutStyle" parent="Widget.MaterialComponents.TextInputLayout.FilledBox"/>
Disable Hint Animation :
<style name="Maf.CardNumberInputLayoutStyle" parent="MafInputLayoutStyle">
<item name="hintAnimationEnabled">false</item>
</style>
Add End Icon :
<style name="Maf.CardCvcEditTextStyle" parent="MafInputLayoutStyle">
<item name="endIconMode">custom</item>
<item name="endIconDrawable">@drawable/ic_maf_cvv_icon_info</item>
</style>
EditText Customization
Merchant can use all attributes exist in EditText
Styles:
<style name="Maf.CardNumberEditTextStyle" parent="MafEditText">
</style>
<style name="Maf.CardCvcEditTextStyle" parent="MafEditText"></style>
<style name="Maf.CardExpiryEditTextStyle" parent="MafEditText"></style>
<style name="Maf.CardHolderNameEditTextStyle" parent="MafEditText"></style>
Examples Of Customization :
Increase TextSize of CardNumber EditText
<style name="Maf.CardNumberEditTextStyle" parent="MafEditText">
<item name="android:textSize">14sp</item>
</style>
Change Font Family of CardNumber EditText
<style name="Maf.CardNumberEditTextStyle" parent="MafEditText">
<item name="android:textSize">14sp</item>
<item name="android:fontFamily">sans-serif-thin</item>
</style>
Change Font Color of CardNumber EditText
<style name="Maf.CardNumberEditTextStyle" parent="MafEditText">
<item name="android:textSize">14sp</item>
<item name="android:fontFamily">sans-serif-thin</item>
<item name="android:textColor">@color/colorBlue</item>
</style>
Field element | Relevant attributes/methods | Type | Description |
---|---|---|---|
Label Hint Text | app:hintText x.setHint("") |
string | Set hint text label of the component. |
Card Number IconGravity | app:cardNumberIconGravity x.setCardNumberIconGravity(Gravity.START) |
boolean | Determine Gravity for Credit Cards icon (Start/End) |
The divider between text input | app:divider_formatter x.setDivider() |
MaterialDivider | Add space between the element, This property is limited only to the Card number and Expiry date. ex etCardNumber.setDivider(MaterialControllersView.MaterialDivider.DASH) |
Enable DatePicker dialog | app:dateFromPickerDialog x.setDatePickerDialog() |
boolean | To enable/disable select date from DatePicker dialog on ExpireDate component. |
Common Methods Allowed
- fun requestEditTextFocus(): Boolean
- fun setEnabled(enabled: Boolean)
- fun addOnFocusChangeListener(callback: OnFocusChangeListener)
- fun setImeOptions(imeOptions: Int)
- fun setStartIconOnClickListener(startIconOnClickListener: OnClickListener)
- fun setEndIconOnClickListener(endIconOnClickListener: OnClickListener)
- fun setError(error: String?)
- fun setOnPaymentCardEventListener(listener: OnPaymentCardEventListener)
- fun isValid(): Boolean
Full Example
XML
<androidx.appcompat.widget.LinearLayoutCompat xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:orientation="vertical"
android:padding="10dp">
<com.majidalfuttaim.mafpay.views.material.MaterialCardNumberView
android:id="@+id/edtCardNumber"
android:layout_width="match_parent"
android:layout_height="wrap_content" />
<com.majidalfuttaim.mafpay.views.material.MaterialCardExpiryView
android:id="@+id/edCardMonthYear"
android:layout_width="match_parent"
android:layout_height="wrap_content" />
<com.majidalfuttaim.mafpay.views.material.MaterialCardCvcView
android:id="@+id/edtCvvNumber"
android:layout_width="match_parent"
android:layout_height="wrap_content" />
<com.majidalfuttaim.mafpay.views.material.MaterialCardHolderView
android:id="@+id/edCardName"
android:layout_width="match_parent"
android:layout_height="wrap_content" />
<com.majidalfuttaim.mafpay.views.RememberMeCheckBox
android:id="@+id/rememberMeSwitch"
android:layout_width="wrap_content"
android:layout_height="wrap_content" />
<com.majidalfuttaim.mafpay.views.TokenizeButton
android:id="@+id/btnToknaize"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginTop="10dp"
app:enableDefaultStyle="true" />
</androidx.appcompat.widget.LinearLayoutCompat>
Java Code
class FullExample : BaseFragment() {
override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View? {
return inflater.inflate(R.layout.fragment_material_tokenize, container, false)
}
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
super.onViewCreated(view, savedInstanceState)
btnToknaize.setUp(verifyType = VerifyType.ThreeDs)
btnToknaize.getResult()!!.observe(viewLifecycleOwner) {
when (val result = it.getContentIfNotHandled()) {
is MafResult.Loading -> {
startLoading()
}
is MafResult.Success<Token> -> {
handleSuccess(result.value)
}
is MafResult.Failure<Token> -> {
handleFailure(result.mafPayError)
}
}
}
btnToknaize.enableDefaultStyle=true
}
private fun handleSuccess(result: Token) {
stopLoading()
Toast.makeText(requireContext(), result.cardToken, Toast.LENGTH_SHORT).show()
}
private fun handleFailure(result: MafPayError) {
stopLoading()
Toast.makeText(requireContext(), result.errorCode + " " + result.errorMessage, Toast.LENGTH_LONG).show()
}
}
RememberMe Component
This UI component is built to enable or disabled storing the customer payment card
RememberMe Component Used with Tokenization Form No Need to extra Code just put it in XML and TokenizationButton will get the result from it .
Note : This component is a normal checkbox
XML Usage
<com.majidalfuttaim.mafpay.views.RememberMeCheckBox
android:id="@+id/rememberMeSwitch"
android:layout_width="wrap_content"
android:layout_height="wrap_content" />
Bank Transfer
This payment method allows merchants to accept bank transfer payments for the services/goods they provide to their customers. Bank transfer payment method available using same integration you use in checkout session.
Link Bank Account
In order for your customer to be able to make payment using bank transfer, first they need to authorise their bank to transfer funds from their account to your account. This is known in their bank account as a 'Beneficiary'. For some banks, creating a beneficiary can have a cool-down period of up to 24 hours.
- accountHolderId: The account holder ID that been created for the customer.
- bankToken: The banks alias name, that has been assigned to a specific user bank.
- activity: The current activity.
- callback: A BankingResponseCallback contained bankToken in success case and MAFPayError in failure case.
fun linkBank( activity: Activity, accountHolderId: String?, bankToken: String?, callback: BankingResponseCallback)
Sample code
MafPay.getInstance().linkBank(requireActivity(), "accountHolder", "bankToken",object :BankingResponseCallback{
override fun onComplete(bankToken: String) {
}
override fun onClose() {
}
override fun onError(error: MafPayError) {
}
})
Get Account Holder Banks
This operation allows merchants to retrieve all banks related to specific accountHolder from MAF Pay.
- callback: is a callback that you define to receive the result object.
fun getAccountHolderBanks(callback: Callback<List<Bank>>)
Sample code
MafPay.getInstance().getAccountHolderBanks(object :Callback<List<Bank>>{
override fun onSuccess(result: List<Bank>?) {
}
override fun onError(error: MafPayError?) {
}
})
Pay With Bank Account
In this step, the customer will confirm the amount they want to transfer from their account to your account. MAF Pay provides bank transfer payment through checkout session component. Once payment initiation has been completed, you will receive the final payment status on your feedback URL configured on MAF Pay portal.
- activity: The current activity.
- checkoutToken: The checkout session token which is required to complete the payment.
- bankToken: The banks alias name, that has been assigned to a specific user bank.
- callback: A PayBankingResponseCallback success case and MAFPayError in failure case.
fun bankTransfer(activity: Activity, checkoutToken: String, bankToken: String, callback: PayBankingResponseCallback)
Sample code
MafPay.getInstance().bankTransfer(requireActivity(), "checkoutToken", "bankToken",object :PayBankingResponseCallback{
override fun onComplete() {
}
override fun onClose() {
}
override fun onError(error: MafPayError) {
}
})
Buy Now Pay Later
MAF Pay provides the ability to offer Buy Now Pay Later (BNPL) providers to your customers with simple UI component integration, you can simply add the BuyNowPayLaterView component to your checkout page and MAF Pay will handle the payment flow for each provider.
XML Usage
<com.majidalfuttaim.mafpay.views.BuyNowPayLaterView
android:id="@+id/buyNowPayLater"
android:layout_width="match_parent"
android:layout_height="wrap_content"
/>
Code Usage
/**
* @param checkoutToken String
*/
fun setup(checkoutToken: String)
BuyNowPayLaterView uses LiveData to expose its result which is an observable data holder class. Unlike a regular observable, LiveData is lifecycle-aware.
buyNowPayLater.getResult()
Note: if you want to support Landscape you must check savedInstanceState and make sure the setup method initialized once.
Sample Code
Java
BuyNowPayLaterView buyNowPayLater = findViewById(R.id.buyNowPayLater);
if(savedInstanceState==null)
buyNowPayLater.setup("CheckoutToken");
buyNowPayLater.getResult().observe(this, stateDataEvent -> {
StateData<BuyNowPayLater> data = stateDataEvent.getContentIfNotHandled();
switch (data.getStatus()){
case SUCCESS:
BuyNowPayLater nowPayLater = data.getData();
break;
case ERROR:
MafPayError error = data.getError();
break;
case CLOSED:
break;
}
});
Kotlin
var buyNowPayLater =findViewById<BuyNowPayLaterView(R.id.buyNowPayLater)
if (savedInstanceState==null)
buyNowPayLater.setup(fragmentArgs.checkoutToken!!)
buyNowPayLater.getResult()?.observe(viewLifecycleOwner, Observer {
val result = it.getContentIfNotHandled()
when (result?.status) {
StateData.DataStatus.SUCCESS -> {
}
StateData.DataStatus.ERROR -> {
}
StateData.DataStatus.CLOSED -> {
}
}
})
Customization
MAF Pay BNPL component has been built with minimalistic and user-friendly styles to accommodate most of well-known designs techniques.
To customize the look and feel of BNPL component you can override the component properties to the desired values, the below table list the possible customization properties:
Option | Format | Description |
---|---|---|
isGrouped | boolean | A flag used to display the component grouped or expanded. |
mainBackground | reference | To set the main component background color |
productsBackground | reference | To set the component child BNPL provider options background color |
mainTitle | string | The text of the BNPL component, the default value is “Buy now pay later”. |
mainTitleTextColor | reference/color | To set the text color of the title. |
mainTitleTextSize | dimension | To set the text size of the title. |
mainTitleVisibility | boolean | To set the visibility of the main title. |
mainFontFamily | reference | To set the text font of the title. |
paymentOptionTitleTextColor | reference/color | To set the text color of the child BNPL provider options. |
paymentOptionTitleTextSize | dimension | To set the text size of the child BNPL provider options. |
paymentOptionFontFamily | reference | To set the text font of the child BNPL provider options. |
tabbyProductsTitleTextColor | reference/color | To set the text color of the child Tabby payment products. |
tabbyProductsTitleTextSize | dimension | To set the text size of the child Tabby payment products. |
tabbyProductsFontFamily | reference | To set the text font of the child Tabby payment products. |
tabbyDescriptionTitleTextColor | reference/color | To set the text color of Tabby description. |
tabbyDescriptionTitleTextSize | dimension | To set the text font of Tabby description. |
tabbyDescriptionFontFamily | reference | To set the text font of Tabby description. |
tabbyButtonTitleTextColor | reference/color | To set the text color of Tabby provider button. |
tabbyButtonTitleTextSize | dimension | To set the text size of Tabby provider button. |
tabbyButtonFontFamily | reference | To set the text font of Tabby provider button. |
tabbyButtonBackgroundColor | Color | To set the background color of Tabby provider button. |
mainErrorTitle | string | Set the error title text of the component error messages. |
mainErrorDescriptionText | string | Set the error description text of the component error messages. |
mainErrorTitleTextColor | reference/color | Set the error title text color of the component error messages. |
mainErrorDescriptionTextColor | reference/color | Set the error description text color of Tabby error messages. |
mainErrorTitleTextSize | dimension | Set the error title text size of the component error messages. |
mainErrorDescriptionTextSize | dimension | Set the error description text size of Tabby error messages. |
mainErrorTitleFontFamily | reference | Set the error title text font of the component error messages. |
mainErrorDescriptionFontFamily | reference | Set the error description text font of Tabby error messages. |
tabbyErrorTitle | string | Set the error title text of Tabby error messages. |
tabbyErrorDescriptionText | string | Set the error description text of Tabby error messages. |
tabbyErrorTitleTextColor | reference/color | Set the error title text color of Tabby error messages. |
tabbyErrorDescriptionTextColor | reference/color | Set the error description text color of Tabby error messages. |
tabbyErrorTitleTextSize | dimension | Set the error title text size of Tabby error messages. |
tabbyErrorDescriptionTextSize | dimension | Set the error description text size of Tabby error messages. |
tabbyErrorTitleFontFamily | reference | Set the error title text font of Tabby error messages. |
tabbyErrorDescriptionFontFamily | reference | Set the error description text font of Tabby error messages. |
spotiiErrorTitle | string | Set the error title text of Spotii error messages. |
spotiiErrorDescriptionText | string | Set the error description text of Spotii error messages. |
spotiiErrorTitleTextColor | reference/color | Set the error title text color of Spotii error messages. |
spotiiErrorDescriptionTextColor | reference/color | Set the error description text color of Spotii error messages. |
spotiiErrorTitleTextSize | dimension | Set the error title text size of Spotii error messages. |
spotiiErrorDescriptionTextSize | dimension | Set the error description text size of Spotii error messages. |
spotiiErrorTitleFontFamily | reference | Set the error title text font of Spotii error messages. |
spotiiErrorDescriptionFontFamily | reference | Set the error description text font of Spotii error messages. |
Sample code
The below code customize the look and feel of the BNPL component.
buyNowPayLater.mainTitleTextColor = Color.GREEN
buyNowPayLater.paymentOptionTitleTextColor = Color.GREEN
buyNowPayLater.isGrouped = false
buyNowPayLater.productsBackground =R.drawable.rounded_border
Tabby Promo Messages
You can implement the snippets from your end using the following links for the pop-up (can be also opened in WebView). We do recommend using the PDP/Cart snippets, with the 'i' button as on the Front-end side. Pop-up URLs for checkout page, payment methods:
- https://checkout.tabby.ai/promos/product-page/installments/en/
- https://checkout.tabby.ai/promos/product-page/installments/ar/
Samsung Pay
Overview
Samsung Pay provides an in-app purchasing experience that allows customers with supported Samsung devices to pay with payment methods stored in their Samsung Pay app.
Integration
To simplify Samsung Pay integration MAF Pay Android SDK provides a SamsungPayButton
component to launch InApp Payments which also can be customized to fit your checkout page.
Usage
<com.majidalfuttaim.mafpay.views.SamsungPayButton
android:id="@+id/btnSamsungPay"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
/>
Code :
Function parameters:
1- Service Id: Represents the unique combination of an app and a Service Type (INAPP_PAYMENT) plus a CSR, and is passed as a parameter to Samsung Pay by MAF Pay in an API call for backend verification and mapping.
2- SamsungResultListener: MAF Pay provides SamsungResultListener callback interface in order to receive the status of the payment transactions.
interface SamsungResultListener {
fun onSuccess(samsungPayPayment: SamsungPayPayment)
fun onFailure(mafpayError: MafPayError)
}
3- SamsungPayRequest: A class used to create and process Samsung Pay request
Kotlin
val supportedCards: ArrayList<SpaySdk.Brand> = ArrayList()
supportedCards.add(SpaySdk.Brand.VISA)
supportedCards.add(SpaySdk.Brand.AMERICANEXPRESS)
supportedCards.add(SpaySdk.Brand.MASTERCARD)
val amountBoxControl = AmountBoxControls(BigDecimal(10000), "AED")
val plainTextControl = PlainTextControl("PRODUCT_ITEM_ID")
plainTextControl.setText("Info", "Info")
var samsungPayRequest = SamsungPayRequest.builder().samsungPayMerchantId("MerchantId")
.merchantName("MerchantName")
.orderNumber("OrderNumber")
.supportedCards(supportedCards)
.addPlainTextControl(plainTextControl)
.addAmountBoxControl(amountBoxControl)
.build()
Java
btnSamsungPay.setup(samsungServiceId = String,
samsungPayListener = SamsungResultListener,
samsungPayRequest = SamsungPayRequest )
Full Example:
Kotlin
class SamsungPayFragment : Fragment(), SamsungResultListener {
override fun onCreateView(
inflater: LayoutInflater, container: ViewGroup?,
savedInstanceState: Bundle?
): View? {
// Inflate the layout for this fragment
return inflater.inflate(R.layout.fragment_samsung_pay_now, container, false)
}
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
super.onViewCreated(view, savedInstanceState)
btnSamsungPay.setup("serviceId",getPaymentRequest(),this)
}
override fun onSuccess(
samsungPayPayment: SamsungPayPayment
) {
Log.e("TAG",samsungPayPayment.walletData)
Log.e("TAG",samsungPayPayment.walletVersion)
Toast.makeText(requireContext(), "onSuccess", Toast.LENGTH_SHORT).show()
}
override fun onFailure(mafpayError: MafPayError) {
Toast.makeText(requireContext(), "errorCode ${mafpayError.errorCode} errorName ${mafpayError.errorMessage}", Toast.LENGTH_SHORT).show()
}
private fun getPaymentRequest(): SamsungPayRequest {
val supportedCards: ArrayList<SpaySdk.Brand> = ArrayList()
supportedCards.add(SpaySdk.Brand.VISA)
supportedCards.add(SpaySdk.Brand.AMERICANEXPRESS)
supportedCards.add(SpaySdk.Brand.MASTERCARD)
val amountBoxControl = AmountBoxControls(BigDecimal(10000), "AED")
val plainTextControl = PlainTextControl("PRODUCT_ITEM_ID")
plainTextControl.setText("Ahmad", "Hamda")
var samsungPayRequest = SamsungPayRequest.builder().samsungPayMerchantId("MerchantId")
.merchantName("MerchantName")
.orderNumber("OrderNumber")
.supportedCards(supportedCards)
.addPlainTextControl(plainTextControl)
.addAmountBoxControl(amountBoxControl)
.build()
return samsungPayRequest
}
}
Google Pay
Overview
Google Pay provides an in-app purchasing experience that allows customers to pay with payment methods stored in their Google Pay wallet app.
Integration
To simplify Google Pay integration MAF Pay Android SDK provides a GooglePayButton component to launch Google Pay payments, which can be customized to fit your checkout page.
XML Usage
<com.majidalfuttaim.mafpay.views.GooglePayButton
android:id="@+id/googlePayButtonNew"
android:layout_width="300dp"
android:layout_height="wrap_content"
app:backgroundMode="black" -> white//black
/>
Implementation
Fragments:
btnGooglePay.setup(fragment = this, checkoutToken = "your checkoutToken")
Activities:
btnGooglePay.setup(activity = this, checkoutToken = "your checkoutToken")
GooglePayButton uses LiveData to expose its result btnGooglePay.getResult() which is an observable data holder class. Unlike a regular observable, LiveData is lifecycle-aware.
Note: getResult() should be called after setup method
btnGooglePay.getResult()?.observe(viewLifecycleOwner, Observer {
val result = it.getContentIfNotHandled()
when (result?.status) {
StateData.DataStatus.SUCCESS -> {
Toast.makeText(requireActivity(), "onComplete" + result.data?.checkoutToken, Toast.LENGTH_SHORT).show()
}
StateData.DataStatus.ERROR -> {
Toast.makeText(requireActivity(), "onError", Toast.LENGTH_SHORT).show()
Toast.makeText(requireActivity(), result.error?.errorMessage + result.error?.errorCode, Toast.LENGTH_SHORT).show()
}
StateData.DataStatus.CLOSED -> {
Toast.makeText(requireActivity(), "onClose", Toast.LENGTH_SHORT).show()
}
}
})
Sample Codes
Kotlin:
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
super.onViewCreated(view, savedInstanceState)
googlePayButtonNew.setup(fragment = this, checkoutToken = "your token")
googlePayButtonNew.getResult()?.observe(viewLifecycleOwner, Observer {
val result = it.getContentIfNotHandled()
when (result?.status) {
StateData.DataStatus.SUCCESS -> {
Toast.makeText(requireActivity(), "onComplete" + result.data?.checkoutToken, Toast.LENGTH_SHORT).show()
}
StateData.DataStatus.ERROR -> {
Toast.makeText(requireActivity(), "onError", Toast.LENGTH_SHORT).show()
Toast.makeText(requireActivity(), result.error?.errorMessage + result.error?.errorCode, Toast.LENGTH_SHORT).show()
}
StateData.DataStatus.CLOSED -> {
Toast.makeText(requireActivity(), "onClose", Toast.LENGTH_SHORT).show()
}
}
})
}
Java:
private GooglePayButton btnGooglePay;
@Override
public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState) {
super.onViewCreated(view, savedInstanceState);
btnGooglePay=view.findViewById(R.id.googlePayButtonNew);
btnGooglePay.setup(this,"MyCheckoutToken");
btnGooglePay.getResult().observe(getViewLifecycleOwner(), stateDataEvent -> {
StateData<GooglePayResult> result = stateDataEvent.getContentIfNotHandled();
switch (result.getStatus()){
case SUCCESS:
GooglePayResult data = result.getData();
break;
case ERROR:
MafPayError error = result.getError();
break;
case CLOSED:
break;
}
});
}
Customization
Google Pay component allows to customize the theme of Google Pay button as follows:
XML:
<com.majidalfuttaim.mafpay.views.GooglePayButton
android:id="@+id/googlePayButtonNew"
android:layout_width="300dp"
android:layout_height="wrap_content"
app:backgroundMode="black" -> white//black
/>
Code:
googlePayButtonNew.backgroundMode = GooglePayButton.BACKGROUND_MODE_WHITE
googlePayButtonNew.backgroundMode = GooglePayButton.BACKGROUND_MODE_BLACK
Binance Pay
Binance Pay is a contactless, borderless and secure cryptocurrency payment technology designed by Binance. Binance Pay allows Binance customer to pay and get paid in crypto from your friends and family worldwide.
How to use
After setting up Binance Pay you are ready to add Binance Pay by using one of the following integration options that MAF Pay provides:
1- MAFPay operation function:
In this integration, you are responsible for creating and maintaining the Binance Pay button on your checkout screen, and you can initiate Binance Pay transaction processing using the function below:
val callback : BinanceCallback = object :BinanceCallback {
override fun onComplete() {
}
override fun onClose() {
}
override fun onError(error: MafPayError) {
}
}
- Call pay method
- checkoutToken: The checkout session token which is required to complete the payment.
- context: The current context.
- callback: A BinanceCallback ON_COMPLETE in success case and MAFPayError in failure case.
val callback : BinanceCallback = object :BinanceCallback {
override fun onComplete() {
}
override fun onClose() {
}
override fun onError(error: MafPayError) {
}
}
MafPay.getInstance().payWithBinance(checkoutToken = "checkoutToken", context = requireContext(), callback = callback)
2- Binance Pay Component
MAF Pay provides a Binance Pay View as a component that you can add to your checkout screen and MAF Pay will handle the interaction with the button and return the appropriate response in callbacks:
a. XMl
<com.majidalfuttaim.mafpay.views.BinancePayView
android:id="@+id/btnBinance"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_gravity="center"/>
b. Setup Button
/**
* * @param activity ComponentActivity
* @param checkoutToken String
*/fun setup(fragment: Fragment, checkoutToken: String)
/**
* * @param activity ComponentActivity
* @param checkoutToken String
*/fun setup(activity: ComponentActivity, checkoutToken: String)
example :
btnBinance.setup(fragment = current Fragment, checkoutToken = "checkoutToken")
Getting Result :
btnBinance.getResult()?.observeEvent(viewLifecycleOwner) {
stopLoading()
when(it.status){
BinanceState.Status.ON_COMPLETE -> {
Toast.makeText(requireContext(), "ON_COMPLETE ",Toast.LENGTH_SHORT).show()
}
BinanceState.Status.ERROR -> {
Toast.makeText(requireContext(), "ERROR ", Toast.LENGTH_SHORT).show()
showAlertMessage("{${it.error?.errorCode} ${it.error?.errorMessage}}")
}
BinanceState.Status.CLOSED -> {
Toast.makeText(requireContext(), "CLOSED", Toast.LENGTH_SHORT).show()
}
BinanceState.Status.LOADING -> {
Toast.makeText(requireContext(), "LOADING", Toast.LENGTH_SHORT).show()
startLoading()
}
}
}
MAF Pay SDK Operations
Get card List
This operation used to retrieve all card tokens “Token” for a specific customer “AccountHolderId”.
Java
MafPay.getInstance().getCardList(new Callback<List<Token>>() {
@Override
public void onSuccess(List<Token> result) {
}
@Override
public void onError(MafPayError error) {
}
});
Kotlin
getInstance().getCardList(object : Callback<List<Token>> {
override fun onError(error: MafPayError) {
}
override fun onSuccess(result: List<Token>) {
}
})
Delete card
This operation used to delete a specific card token.
Function parameters:
- cardToken: The card alias name, that has been assigned to a specific user card.
java
MafPay.getInstance().deleteCard("CardToken", new Callback<Boolean>() {
@Override
public void onSuccess(Boolean result) {
}
@Override
public void onError(MafPayError error) {
}
kotlin
MafPay.getInstance().deleteCard("CardToken", object : Callback<Boolean> {
override fun onSuccess(result: Boolean) {}
override fun onError(error: MafPayError) {}
})
Confirm Verification
You can use this operation to complete the verification process, the user provides the verification amount.
You will pass the verification amount and cardToken as part of confirm verification.
MAF Pay checks if the amounts match then card status is set to verified
Function parameters:
- amount: The amount value that the customer entered.
Java
MafPay.getInstance().confirmVerification(12, "cardToken", new Callback<Boolean>() {
@Override
public void onSuccess(Boolean result) {
}
@Override
public void onError(MafPayError error) {
}
});
Kotlin
MafPay.getInstance().confirmVerification(12.0, "CardToken", object : Callback<Boolean> {
override fun onSuccess(result: Boolean) {}
override fun onError(error: MafPayError) {}
})
Set card as default
You can use this operation to set card as default to a specific card token.
Function parameters:
- cardToken: the card alias name, that has been assigned to a specific user card.
- accountHolderId: The account holder ID that been created for the customer.
fun setCardAsDefault(cardToken: String, accountHolderId: String? = null, callback: Callback<Base>)
Java
MafPay.getInstance().setCardAsDefault("CardToken", "AccountholderID", new Callback<Base>() {
@Override
public void onSuccess(Base result) {
}
@Override
public void onError(MafPayError error) {
}
});
Kotlin
MafPay.getInstance().setCardAsDefault("CardToken", "AccountholderID", object : Callback<Base> {
override fun onSuccess(result: Base) {}
override fun onError(error: MafPayError) {}
})
Processing 3D Secure 2
Once submitting a payment transaction MAF Pay will start the process of authenticating the card holder using 3D Secure 2 and it will generate a unique 3DS authentication reference “threeDsAuthId” that will be used to complete the 3DS flow.
Function parameters:
- threeDsAuthId: A unique reference for the 3D Secure authentication generated by the gateway, this parameter used to complete the 3D Secure 2 authentication.
- context: The current context.
fun processThreeDSAuth(context: Context, threeDsAuthId: String, callback: Callback<HashMap<String, String>>)
Sample code
MafPay.getInstance().processThreeDSAuth(requireContext(), threeDsAuthId, object :Callback<HashMap<String,String>>{
override fun onSuccess(result: HashMap<String, String>?) {
}
override fun onError(error: MafPayError?) {
}
})
MAF Pay SDK Objects
Response Token Object
The token object contains the result of the tokenization request, the values that the token object are:- cardToken: The card alias name, that has been assigned to a specific user card.
- cardBrand: such as VISA, MasterCard
- cardType: such as Credit, Debit
- cardBin: The bank identification number (BIN) is the first six digits of the card number.
- cardMaskedNumber: The masked card number. For example, 400555******0019
- expiryMonth: The card expiry month.
- expiryYear: The card expiry year.
class Token(
val accountHolderId: String?=null,
val cardBin: String?,
val cardBrand: String?,
val cardHolderName: String?=null,
val cardMaskedNumber: String,
val cardToken: String?,
val cardType: String?,
val expiryMonth: String?,
val expiryYear: String?,
val status: String?=null
)
Response BuyNowPayLater Object
The BuyNowPayLater object contains the result of the Buy Now Pay Later checkout request. the values that BuyNowPayLater object have are:
- checkoutToken : the checkoutToken that have been used for the checkout process
data class BuyNowPayLater(val checkoutToken: String)
Response SamsungPayPayment Object
SamsungPayPayment object contains the encrypted data of the card selected by the customer, which will be passed to MAF Pay APIs for payment processing:
- walletData: The encrypted customer card information.
- walletVersion: Version on transaction api
data class SamsungPayPayment(val walletData: String?, val walletVersion: String?)
Bank Object
The Bank object contains the result of the bank information. the values that Bank object have are:
- bankToken: The bank token
- status: The status
- bankName: The bank name
- bankCountry: The bank country
- bankLogo: The bank logo
data class Bank(
val bankCountry: String,
val bankLogo: String,
val bankName: String,
val bankToken: String,
val status: String)
MAF Pay SDK Errors
Card Error
CardError Enum returns errors whenever Card values validation fails. The object contains the following fields:
- errorMessage : It returns a description for error.
- errorCode : It returns error code for error.
public enum CardError {
INVALID_CARD_NUMBER
INVALID_CARD_LENGTH
INVALID_CVC_LENGTH
INVALID_CVC_FORMAT
INVALID_CARD_HOLDER_NAME
INVALID_CARD_EXPIRY_MONTH
INVALID_CARD_EXPIRY_YEAR
INVALID_CARD_EXPIRY_DATE
CARD_UNSUPPORTED
EMPTY_CARD_NUMBER
EMPTY_CARD_DATE
EMPTY_CARD_CVC
}
MAF Pay Error
MAFPayError Enum returns errors whenever errors occur while initiating calls to MAF Pay backend system. The object contains the following fields:
- errorMessage : It returns a description for error.
- errorCode : It returns error code for error.
- extraParams : It returns HashMap that contains that params help to identify error reason.
public enum MafPayError {
ERROR_SERVER_ERROR
ERROR_INTERNAL_ERROR
ERROR_TIME_OUT
ERROR_NO_INTERNET_CONNECTION
}
ErrorType | errorCode | errorDescription |
---|---|---|
noInternet | 5003 | Missing authentication data |
timeOut | 5001 | Missing identifier data |
serverError | Please refer to Server Errors | |
internalError | Please refer to section Internal Error below |
Internal Error
InternalError Enum returns all errors that will occur while internal validations such as :Error Type | Code | Description |
---|---|---|
ERROR_INVALID_CARD_NUMBER | 101 | Invalid Card Number |
ERROR_INVALID_CARD_EXPIRY_DATE | 102 | Invalid Expiry Date |
ERROR_INVALID_CARD_SECURITY_CODE | 103 | Invalid Security Code |
ERROR_CANNOT_PARSE_JSON | 104 | Error parsing the response |
ERROR_MISSING_CARD_NUMBER_View | 105 | Missing Card Number View |
ERROR_MISSING_CARD_DATE_View | 106 | Missing Card DATE View |
ERROR_MISSING_CARD_CVV_View | 107 | Missing Card CVV View |
ERROR_MISSING_AUTHENTICATION_CREDENTIALS | 9000 | Missing credentials: API Key or authorization one of them must be filled. |
ERROR_MISSING_MERCHANT_IDENTIFIER | 9001 | Missing Keys : Merchant-id or Partner-Id one of them must be filled. |
ERROR_MISSING_AUTHENTICATION | 9002 | Missing credentials: authorization must be filled. |
ERROR_ALL_IDENTIFIERS_FILLED | 9003 | One of the MERCHANT-ID OR PARTNER-ID must be field not both |
ERROR_VERIFICATION_CANCELED | 9006 | Card Verification was canceled |
ERROR_WEBVIEW_VERIFICATION | 9007 | Errors returned from the WebView, Please refer to Server Errors |
ERROR_TABBY_SESSION_ID_IS_EMPTY | 9008 | Tabby session ID is empty |
ERROR_TABBY_ID_IS_EMPTY | 9009 | Tabby ID is empty |
TABBY_ACCESS_STORAGE_PERMISSION | 9012 | Storage permission is needed to upload your ID, Go to settings and enable the permission |
TABBY_PRODUCT_TYPE_IS_EMPTY | 9013 | Tabby product type is Empty |
CERTIFICATE_NOT_MATCH | 9014 | Certificate does not match, please contact your support team |
SAMSUNG_PAY_NOT_READY | 9016 | Samsung pay not ready |
SAMSUNG_PAY_NEED_UPDATE | 9017 | Samsung pay needs update |
SAMSUNG_PAY_SETUP_NOT_COMPLETE | 9018 | Samsung pay not completed |
SAMSUNG_PAY_NOT_SUPPORTED | 9019 | Samsung pay not supported |
SAMSUNG_PAY_GENERIC_ERROR | 9020 | Message returned by Samsung pay |
SAMSUNG_PAY_INTERNAL | 9021 | Message returned by Samsung pay |
BINANCE_PAY_NOT_SUPPORTED | 9026 | Binance Pay not supported |
Web Library
Using MAF Pay library will provide the comfort during implementing the payment page, by providing the pre-defined web components that validate and process the user inputs by its own.
MAF Pay payment services allows merchants to accept payments by integrating with the payment APIs in the Javascript Framework of their choice. It offers:
- Customizable UI components.
- Validations to limit the chances of incorrect data entry.
- An easier API integration process.
- Tokenization service to securely store customer's data.
Setup MAF Pay Library
Include MAF Pay Library script on your checkout page by adding it to the head of your HTML file. Always load the library directly from “https://engineering.mafpayments.com” to remain PCI compliant. Do not include the script in a bundle or host a copy of it yourself.
index.html
<head>
<title> payment</title>
<script type="module" src="https://engineering.mafpayments.com/npm/mafpay/mafpay.esm.js"></script>
<script nomodule src="https://engineering.mafpayments.com/npm/mafpay/mafpay.esm.js"></script>
<link rel="stylesheet" href="https://engineering.mafpayments.com/npm/mafpay/mafpay.css">
</head>
We also provides thin wrappers around MAF Pay Web Library, that allows you to add UI components to any React, Angular, and Vue apps.
React: For more details on how to use React version please follow this link MAF Pay React Web Library
Angular: For more details on how to use Angular version please follow this link MAF Pay Angular Web Library
Vue: For more details on how to use Vue version please follow this link MAF Pay Vue Web Library
Setup language
To setup the preferred language you can use the language parameter “lang”. You can set the language parameter by setting the required language value to window.MafPay.lang, the possible values are:
language | values |
---|---|
Arabic | ar |
English | en |
The below sample code sets the language to arabic.
<script>
window.MafPay = {
lang: 'ar'
}
</script>
change language in runtime
To change the language during the runtime you can use setLanguage() function. You can change the language by calling setLanguage() function and pass the required language value as a parameter.
The below sample code sets the language to arabic.
<script>
window.MafPay.setLanguage('ar')
</script>
to get the selected language you can call geLanguage() function and it will return the current language as a string
The below sample code gets the current language.
<script>
window.MafPay.getLanguage() //output: 'ar'
</script>
Integrate Card Form with your Web/App
To build the card form on your site, you can use one of the following two options:
- Create Card Form Using Separate Components: This option gives you more flexibility if you are looking for design customization options, as it gives you complete control over adding each component of the card to create your credit/debit card form.
- Create Card Form Using Wrapper Component(single component): If you are looking for simplicity and at the same time a ready-to-use credit / debit card form, then this option will be the right choice for you. This option includes all the options required for the card form using only one component.
Create Card Form Using Separate Components:
This payment form consists of six customizable UI components:
- <mafpay-card-number>
- <mafpay-card-holder-name>
- <mafpay-card-expiry>
- <mafpay-card-cvc>
- <mafpay-remember-card>
- <mafpay-card-submit>
These UI components are built to securely collect your customers' payment details without having you deal with any sensitive data.
To create the card payment form and apply the required UI customization you need to follow the below steps:
Creating the card payment form:
Create an empty form that will consist of three attributes:
- Method with a POST request.
- Action with MAF Pay tokenization API "https://payment.sandbox.mafpayments.com/tokenize".
- noValidate to prevent native form validation.
Since the API requires additional parameters, add three hidden inputs to the form as the following:
- merchantId: represent the merchant ID of your account, this will be provided by the MAF Pay team.
- apiKey: represent the API Key of your account, this will be provided by the MAF Pay team.
- Command: the value is "tokenize".
in 3DS 2 flow a new parameter is needed:
tokenizev2: the value is "true"
index.html
<form method="POST" action="https://payment.sandbox.mafpayments.com/tokenize" noValidate>
<div class="payment-form">
//The values of these fields will be provided by the operation team
<input type="hidden" name="merchantId" value="SIXTFWBQ0923939"/>
<input type="hidden" name="apiKey" value="StoreAuthValue5700"/>
<input type="hidden" name="command" value="tokenize"/>
//For 3DS2 flow
<input type="hidden" name="tokenizev2" value="true"/>
</div>
</form>
Add the payment card components
After creating the payment form, you can add the payment card components inside the form.
index.html
<form method="POST" action=" https://payment.sandbox.mafpayments.com/tokenize" noValidate>
<div class="payment-form">
<input type="hidden" name="merchantId" value="SICTFWBQ0929293"/>
<input type="hidden" name="apiKey" value="StoreAuthValue5700"/>
<input type="hidden" name="command" value="tokenize" />
//For 3DS2 flow
<input type="hidden" name="tokenizev2" value="true"/>
// MAF Pay UI components
<mafpay-card-number></mafpay-card-number>
<mafpay-card-holder-name></mafpay-card-holder-name>
<mafpay-card-expiry></mafpay-card-expiry>
<mafpay-card-cvc></mafpay-card-cvc>
<mafpay-remember-card></mafpay-remember-card>
<mafpay-card-submit></mafpay-card-submit>
</div>
</form>
The default look and feel will be like the following:
UI customization
MAF Pay web payment components has been built with minimalistic and user-friendly styles to accommodate most of well-known designs techniques, the main characteristics of MAF Pay web components are:
- They will expand their width based on their parent container.
- Each component contained within a grey outlined box.
- Container box lines will change color from grey to red in case of any validation error.
To customize the look and feel of the container boxes, you can override ".mafp-card-field" class, the below example will apply shadow effect around the fields:
styles.css
.mafpay-card-field {
box-shadow: 5px 10px 8px #888888;
margin-bottom: 12px;
}
Regarding the customization of the submit component, you can use the CSS styles directly, the following example changes the submit component color to black with white text:
styles.css
.submit-container button {
color: #fff;
background-color: #000;
width: 100%;
height: 46px;
}
Default styles
MAF Pay web payment component provides a default style for the components, the default style includes UI customization for input fields based on their state, idle, error, success, and focus, also for submit button state, loading, disabled and idle.
To enable the default style, you need to set window.MafPay.defaultStyle value as true, please note that the default value for this option is false.
The sample code below demonstrates how to enable the default style
<script>
window.MafPay = {
defaultStyle: true
}
</script>
The default styles look and feel will be like the following:
MAF Pay components provide additional tag properties that allow further component customizations such as labels text, the following table contains the list of possible component properties.
MAF Pay Component | Property | Description |
---|---|---|
mafpay-card-number | placeholder | Used to change the placeholder text displayed inside the component, the default value is "Card number". |
mafpay-card-holder-name | placeholder | Used to change the placeholder text displayed inside the component, the default value is "Full name". |
mandatory | Used to determine whether the field is mandatory or not, the default value is "false". | |
mafpay-card-expiry | placeholder | Used to change the placeholder text displayed inside the component, the default value is "MM/YY". |
mafpay-card-cvc | placeholder | Used to change the placeholder text displayed inside the component, the default value is "CVC". |
masked | A flag to enable or disable the field value masking, the default value is "true". | |
tooltip | A flag to enable or disable the CVC help tooltip, the default value is "true". | |
mafpay-remember-card | placeholder | Used to change the placeholder text displayed inside the component, the default value is "Remember this card". |
mafpay-card-submit | label | Used to change the text displayed inside the component, the default value is "Submit". |
default-loading | Used to enable MafPay default loading screen, the default value is false. |
Example:
To disable CVC masking, change the masked property to "false" as below:
<mafpay-card-cvc masked="false"></mafpay-card-cvc>
Also to enable Maf Pay default loading, change the default-loading property to "true" as below:
<mafpay-card-submit default-loading="true"></mafpay-card-submit>
Components value validations
MAF Pay components trigger events when a validation error occurs, these validations triggers when the component reaches its required length or loses focus, the below examples show a case of validation error and a valid input value result messages.
Validation error message:
{
"error":{
"errorMessage": "invalid credit card number",
"errorCode": "INVALID_CARD_NUMBER"
}
"status": "INVALID"
}
Successful validation message:
{
"status": "VALID"
}
In order to receive the validation statues register to the status events by adding an event listener on a specific component, The following example adds an event listener on mafpay-card-number:
index.js
const cardNumberElement = document.querySelector("mafpay-card-number");
cardNumberElement.addEventListener("cardNumberStatus", event => {
// event handler code
});
The below table lists all validation errors per component:
MAF Pay Component | Validation status variable | Error code | Description |
---|---|---|---|
mafpay-card-number | cardNumberStatus | INVALID_CARD_NUMBER | The card number field does not pass card format check. |
CARD_NUMBER_INCOMPLETE | The card number field does not meet the length required. | ||
CARD_NUMBER_EMPTY | The card number field is empty. | ||
mafpay-card-holder-name | cardHolderNameStatus | INVALID_CARD_HOLDER_NAME | The card holder name field consist of numbers only or contains special characters. |
mafpay-card-expiry | cardExpiryStatus | INVALID_EXPIRY_DATE | The expiration date field is incomplete. |
EXPIRY_DATE_EXPIRED | The expiration date set to an expired card. | ||
EXPIRY_DATE_EMPTY | The expiration date field is empty. | ||
mafpay-card-cvc | cardCvcStatus | INVALID_CVC | The security code field is incomplete. |
CVC_EMPTY | The security code field is empty. | ||
mafpay-card-submit | submitStatus | INVALID_CARD_DETAILS | At least one or more card detail is invalid. |
MAF Pay provides callback event to receive tokenization response when tokenizev2 parameter is provided with value set to "true" , the callback is as below:
element.addEventListener('tokenizationComplete', event => {
console.log('Processing response event ', event.detail);
})
Maf Pay provides a method called "resetField" for the below components to let the client be able to reset the fields:
- <mafpay-card-number>
- <mafpay-card-holder-name>
- <mafpay-card-expiry>
- <mafpay-card-cvc>
- <mafpay-remember-card>
cardNumberElement.resetField();
Bootstrap Example:
index.html
<form method="POST" action="https://payment.sandbox.mafpayments.com/tokenize/sdk" noValidate>
<div class="payment-form container">
<div class="row">
<input type="hidden" name="merchantId" value="SIXTFWBQ092939"/>
<input type="hidden" name="apiKey" value="StoreAuthValue5700"/>
<input type="hidden" name="command" value="tokenize"/>
<mafpay-card-holder-name class="col-12 mb-3"></mafpay-card-holder-name>
<mafpay-card-number class="col-12 col-lg-5 mb-3"></mafpay-card-number>
<mafpay-card-expiry class="col-7 col-lg-2"></mafpay-card-expiry>
<mafpay-card-cvc class="col-5 col-lg-2"></mafpay-card-cvc>
<mafpay-card-submit class="col-12 col-lg-3"></mafpay-card-submit>
</div>
</div>
</form>
styles.css
html, body {
height: 100%;
}
body {
display: flex;
justify-content: center;
align-items: center;
background: #f0f4f7;
}
.payment-form {
border: 1px solid transparent;
border-radius: 4px;
box-shadow: 0 2px 10px 0 rgba(0, 0, 0, 0.08);
background-color: #ffffff;
padding: 21px 41px;
}
.submit-container button {
color: #fff;
background-color: #000;
width: 100%;
height: 46px;
}
Using the same example but with window.MafPay.defaultStyle set to true :
Create Card Form Using Wrapper Component(single component):
MafPay web component provide a ready to use card form with our default design using only one component.
MAF Pay card form component provides config object which has properties that allow further component customizations, the following table contains the list of all possible config properties.
Property | Description |
---|---|
tokenizev2 | Used to add tokenizev2 property to payment form. |
verifyCard | Used to add verifyCard property to payment form. |
merchantId | Used to add merchantId property to payment form, this field is required. |
command | Used to add command property to payment form, this field is required. |
apiKey | Used to add apiKey property to payment form. |
accountHolderId | Used to add accountHolderId property to payment form. |
auth0Token | Used to add auth0Token property to payment form. |
cardNumberPlaceHolder | Used to change the placeholder text displayed inside the card number component. |
cardCvcPlaceHolder | Used to change the placeholder text displayed inside the card cvc component. |
rememberCardPlaceHolder | Used to change the placeholder text displayed inside the card remember component. |
showRememberCardCheckbox | Used to show/ hide card remember component, the default value is true. |
cardCvcMasked | A flag to enable or disable the field value masking. |
cardCvcTooltip | A flag to enable or disable the CVC help tooltip. |
cardExpiryPlaceHolder | Used to change the placeholder text displayed inside the card expiry component. |
cardHolderNamePlaceHolder | Used to change the placeholder text displayed inside the card holder name component. |
cardDefaultPlaceHolder | Used to change the placeholder text displayed inside the card default component. |
isHolderNameRequired | A flag to mark the card holder name as mandatory or not. |
submitLabel | Used to change the label text displayed inside the submit button. |
defaultLoading | Used to enable MafPay default loading screen, the default value is false. |
The example below demonstrates how to use mafpay-card-form with config object:
<mafpay-card-form></mafpay-card-form>
const config = {
tokenizev2: true,
verifyCard: 'threeds',
merchantId: '<YOUR MERCHANT ID>',
apiKey: '<API KEY>',
command: 'tokenize',
cardCvcTooltip: true,
}
document.querySelector('mafpay-card-form').setAttribute('config', JSON.stringify(config))
You can listen to all events related to the card form component using on()
method, the method takes two parameters:
event name and callback function(the function will be called once the event has been emitted).
To reset all fields inside card form, you can use resetFields()
method.
The example below, shows how to listen to mafpay-card-form
component events and reset the form fields.
<mafpay-card-form></mafpay-card-form>
<button onclick="resetFields()">reset</button>
const config = {
tokenizev2: true,
verifyCard: 'threeds',
merchantId: '<YOUR MERCHANT ID>',
apiKey: '<API KEY>',
command: 'tokenize',
cardCvcTooltip: true,
}
const cardForm = document.querySelector('mafpay-card-form')
cardForm.setAttribute('config', JSON.stringify(config))
cardForm.addEventListener('ready', () => {
cardForm.on('tokenizationComplete', tokenizationComplete);
cardForm.on('cardHolderNameStatus', cardHolderNameStatus);
cardForm.on('cardExpiryStatus', cardExpiryStatus);
cardForm.on('cardCvcStatus', cardCvcStatus);
cardForm.on('cardNumberStatus', cardNumberStatus);
})
function resetFields() {
cardForm.resetFields()
}
function tokenizationComplete(event) {
console.log('tokenizationComplete', event)
}
function cardHolderNameStatus(event) {
console.log('cardHolderNameStatus', event)
}
function cardExpiryStatus(event) {
console.log('cardExpiryStatus', event)
}
function cardCvcStatus(event) {
console.log('cardCvcStatus', event)
}
function cardNumberStatus(event) {
console.log('cardNumberStatus', event)
}
The wrapper component look and feel will be like the following on desktop (large screens):
The wrapper component look and feel will be like the following on mobile (small screens):
Card Form Style Customization:
MAF Pay card form component provides css class names that allow further style customizations, the following example shows how to customize the card form component.
<!DOCTYPE html>
<html dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0">
<title>Card form custom style example</title>
<script nomodule src="https://engineering.mafpayments.com/npm/mafpay/mafpay.esm.js"></script>
<script type="module" src="https://engineering.mafpayments.com/npm/mafpay/mafpay.esm.js"></script>
<link rel="stylesheet" href="https://engineering.mafpayments.com/npm/mafpay/mafpay.css">
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Monda&display=swap" rel="stylesheet">
<style>
body {
font-family: 'Monda', sans-serif;
}
input, button, input::placeholder {
font-family: 'Monda', sans-serif;
}
.mafpay-default-field {
background: transparent;
border-radius: 8px;
border: 2px solid #EFC077;
box-shadow: 0px 2px 4px rgb(0 0 0 / 50%), 0px 1px 6px rgb(0 0 0 / 25%);
height: 55px;
}
.mafpay-default-field input {
color: white;
background: transparent;
}
.mafpay-default-field input::placeholder {
color: white;
}
.mafpay-default-card-submit {
background: #EFC077;
height: 55px;
border-radius: 8px;
}
.tooltip-label svg {
stroke: #EFC077;
}
.mafpay-default-payment-form {
background-color: #212E63;
border-radius: 10px;
}
.mafpay-default-payment-form .mafpay-form-header .mafpay-form-title {
color: white;
}
.mafpay-default-checkbox {
color: white;
}
.mafpay-checkbox-container .mafpay-checkmark {
background-color: #EFC077;
border-radius: 5px;
}
.mafpay-checkbox-container input:checked ~ .mafpay-checkmark {
background-color: #EFC077;
}
</style>
</head>
<body>
<mafpay-card-form style="margin: 100px auto auto;"></mafpay-card-form>
<script>
window.MafPay = {
env: 'stg',
lang: 'en'
}
const config = {
tokenizev2: true,
verifyCard: 'threeds',
merchantId: '<YOUR MERCHENT ID>',
apiKey: '<YOUR API KEY>',
command: 'tokenize',
cardCvcMasked: false,
cardCvcTooltip: true,
isHolderNameRequired: false,
showRememberCardCheckbox: true
}
const cardForm = document.querySelector('mafpay-card-form')
cardForm.setAttribute('config', JSON.stringify(config))
</script>
</body>
</html>
The customized component look and feel will be like the following on desktop (large screens):
The customized component look and feel will be like the following on mobile (small screens):
Checkout Component
MAF Pay checkout component provides a simple interface to create and manage checkout sessions that provide the ability to offer Buy Now Pay Later (BNPL) service providers and other payment options for the customers.
Setup the environment
To setup the correct environment you can use the environment parameter “env”. You can set the environment parameter by setting the required environment value to window.MafPay.env, the possible values are:
environment | value |
---|---|
Sandbox | sandbox |
Production | production |
The below sample code sets the environment to sandbox.
<script>
window.MafPay = {
env: 'sandbox'
}
</script>
Using Checkout Session Component
The component can be used anywhere on the checkout page by declaring its tag as below.
<mafpay-checkout token="Checkout Token"></mafpay-checkout>
The component expects a mandatory checkout token that has been acquired from the server-to-server call. The token can be provided lazily too. The following is an example of setting the token after fetching the value from an async call.
const { checkoutToken } = await createCheckoutSession(); // createCheckoutSession() function implementation is defined by the merchant
document.querySelector('mafpay-checkout').setAttribute('token', checkoutToken);
Component Properties
Property | Attribute | Description | Type | Default |
---|---|---|---|---|
grouped | grouped | To group payment options by type. Default is false. | boolean | false |
token | token | The token generated by MAF Pay checkout API. This prop is required. | string | undefined |
enable-google-pay | enable-google-pay | This attribute can be used to control whether or not the Google Pay button is displayed in the checkout component (this option is enabled by default) | boolean | true |
google-pay-merchant-id | google-pay-merchant-id | Your merchant Id from google pay business console. (Please note that this step is not required in the testing phase). | string | undefined |
google-pay-button-color | google-pay-button-color | Please check Apple Pay for web guide for more details. | string | 'default' |
google-pay-button-type | google-pay-button-type | Please check Google Pay customization guide for more details. | string | 'buy' |
enable-apple-pay | enable-apple-pay | This attribute can be used to control whether or not the Apple Pay button is displayed in the checkout component (this option is enabled by default) | boolean | true |
enable-tamara | enable-tamara | This attribute can be used to control whether or not Tamara button is displayed in the checkout component (this option is enabled by default) | boolean | true |
apple-pay-button-style | apple-pay-button-style | Please check Apple Pay for web guide for more details. | string | 'black' |
apple-pay-button-type | apple-pay-button-type | Please check Apple Pay for web guide for more details. | string | 'buy' |
apple-pay-total-amount-label | apple-pay-total-amount-label | The total amount label that will be shown inside Apple Pay pop-up dialog | string | 'Total' |
redirect-url | redirect-url | If this attribute is true and the user want to checkout using Tabby, we will fire the checkoutRedirectUrl event with the redirectUrl that needed to be redirected to complete the checkout session using tabby portal, instead of showing a popup to complete the checkout session, and after completing the payment the Tabby portal will redirect him to the redirect URL that you have configured before in our portal. |
boolean | 'false' |
Note: if redirect-url
is enabled and after the completion of the Tabby checkout process, customers will be redirected to your payment result page redirectUrl along with the valid response and signature(please refer to redirection response section for more details.).
You will receive pay/authorize response on your transaction feedback URL configured on your merchant account. It is highly advised that you rely on server-to-server notification to receive the payment status as the pay/authorize requests are prone to redirection interruption issues.
Grouping sample code
<mafpay-checkout token=" Checkout Token " grouped></mafpay-checkout>
Events
MAF Pay provides callback events to receive the status of the payment transactions, the callbacks are as below:
Event | Description | Type |
---|---|---|
checkoutClosed | Triggers when the customer closes the lightbox of any checkout payment options. This does not necessarily mean that the user completed the payment flow. It can be useful to indicate customer behavior. | CustomEvent<CheckoutCallback> |
checkoutCompleted | This indicates that the checkout session has reached a terminating state (either success or failure). The final results can be retrieved from the server-to-server feedback. | CustomEvent<CheckoutCallback> |
checkoutError | Triggers whenever an error occurs within the payment flow | CustomEvent<ErrorCallback<any>> |
checkoutRedirectUrl | Triggers with Tabby and Tamara when passing redirect-url attribute as true , and you will receive the redirectUrl that needed to be redirected to complete the checkout session |
CustomEvent<{ redirectUrl: string, paymentOption: 'TAMARA |
Customization
MAF Pay web library provides the ability to customize the look and feel of MAF Pay checkout component as follows:
Customizing Labels
Labels can be edit or localized by passing a messages slot to mafpay-checkout component. The following example changes the label of "Buy now pay later" title to "BUY NOW PAY LATER":
<mafpay-checkout token="CH16200377444954128465" grouped>
<script type="application/json" slot="messages">
{
"bnpl_title": "BUY NOW PAY LATER"
}
</script>
</mafpay-checkout>
Global Label Configuration
Labels can also be overwritten using global configuration as follows:
<script>
window.MafPay = {
labels: {
bnpl_title: 'BUY NOW PAY LATER',
// ...
}
}
</script>
All labels can be edited using the messages slot or the global configuration. You can mix both methods together; however, labels provided in the messages slots are given priority over the global configuration. Refer to the table below for the list of all labels:
Error Code | Default |
---|---|
bnpl_title | Buy now pay later |
others_title | Other payment options |
tabby_title | Pay with Tabby |
tabby_installments_name | Split in 4 payments with Tabby |
tabby_installments_description | No fees or interest, any debit or credit card accepted, pay 25% now and the rest over 3 months |
tabby_installments_buttonLabel | Pay in installments |
tabby_error_606_title | Sorry, you are not eligible for tabby with this order |
tabby_error_606_desc | Try using a different payment option |
tabby_error_607_title | Oops, something went wrong |
tabby_error_607_desc | Tabby is not available right now. Please try again later |
spotii_title | Pay with Spotii |
spotii_error_606_title | Sorry, you are not eligible for Spotii with this order |
spotii_error_606_desc | Try using a different payment option |
spotii_error_607_title | Oops, something went wrong |
spotii_error_607_desc | Spotii is not available right now. Please try again later |
tamara_title | Pay with Tamara |
tamara_installments_name | Split into 3 payments with no fees |
tamara_installments_description | Split into 3 payments, one today and the rest within 60 days. |
tamara_installments_buttonLabel | Pay in 3 installments |
tamara_error_generic_title | Oops, something went wrong. |
tamara_error_generic_desc | Please try again later. |
tamara_error_606_title | Sorry, you are not eligible for Tamara with this order |
tamara_error_606_desc | Try using a different payment option |
tamara_error_607_title | Oops, something went wrong. |
tamara_error_607_desc | Tamara is not available right now. Please try again later. |
google_pay_title | Pay with GooglePay |
apple_pay_title | Apple Pay |
Errors
Handling errors can be performed by listening to checkoutError events. All errors are emitted as CustomEvent that contains the same object structure.
{
// ...
detail: {
errorCode: "CODE";
errorMessage: "Some user-friendly message";
}
}
The list of available error codes are:
Error Code | Description |
---|---|
9020 | Missing checkout token |
9021 | Incorrect checkout token |
9022 | Failed to parse customer labels due to wrong JSON format |
113 | Transaction still processing |
164 | Invalid/Expired checkout token |
165 | Transaction already paid |
Tabby Promo Messages
tabby provides JS to be placed on the Product/Cart and Checkout pages. It contains the split price message and popup presented when customers want to learn more.
- Create an empty div with a unique selector (preferably - id):
<div id="TabbyPromo"></div>
Put that div where you want tabby Promo Snippet to be shown (preferably - near the product price or "Add to cart" button for the product page and near the order total amount or "Proceed to checkout" button for the cart page). tabby Promo Snippet will be injected in that div:
Customers' clicks on "Learn more" link or tabby Logo will trigger the popup showing.
- Create 2 scripts:
<script src="https://checkout.tabby.ai/tabby-promo.js"></script>
<script>
new TabbyPromo({
selector: '#TabbyPromo', // required, content of tabby Promo Snippet will be placed in element with that selector
currency: 'AED', // required, currency of your product
price: '500.00', // required, price or your product
installmentsCount: 4, // Optional - custom installments number for tabby promo snippet (if not downpayment + 3 installments)
lang: 'en', // optional, language of snippet and popups, if the property is not set, then it is based on the attribute 'lang' of your html tag
source: 'product', // optional, snippet placement; `product` for product page and `cart` for cart page
api_key: 'PUBLIC_API_KEY' // optional, MAFPay will provide the value for the API key
});
</script>
Tamara
Tamara is a payment option that give you the ability to shop and split your payments. To add Tamara to your checkout page, you have two options: the Checkout Component or the standalone component.
Setup the environment
To setup the correct environment you can use the environment parameter “env”. You can set the environment parameter by setting the required environment value to window.MafPay.env, the possible values are:
environment | value |
---|---|
Sandbox | sandbox |
Production | production |
window.MafPay = {
env: sandbox
}
Using Tamara Component
The component can be used anywhere on the page by declaring its tag as below, this component will render the Tamara payment button only, and you have to handle the rest of the UI from your side.
<mafpay-tamara-button token="<Your Checkout token>"></mafpay-tamara-button>
Component Properties
Property | Description | Type | Default |
---|---|---|---|
token | The token generated by MAF Pay checkout API. This prop is required. | string | undefined |
Events
Tamara button component provides callback events to receive the status of the payment transactions, the callbacks are as below:
Event | Description | Type |
---|---|---|
tamaraLoading | Triggers when start/finish loading the component. You will receive { isLoading: true } when starting the loading and { isLoading: false } when finishing the loading. |
CustomEvent<{ isLoading: boolean }> |
tamaraError | Triggers whenever an error occurs within the payment flow | CustomEvent<ErrorCallback<any>> |
tamaraRedirectUrl | Triggers the redirectUrl that needed to be redirected to complete the checkout session |
CustomEvent<{ redirectUrl: string, paymentOption: 'TAMARA' }> |
Example
const tamaraElement = document.querySelector('mafpay-tamara-button');
tamaraElement.addEventListener("tamaraRedirectUrl", event => {
console.log('tamaraRedirectUrl',event.detail)
});
3D Secure 2
In order to complete the customer authentication MAF Pay 3DS component will handle the new 3DS2 authentication steps which include data collection and display the 3DS2 issuer pages whenever advised by the card issuer.
Setup the environment
To setup the correct environment you can use the environment parameter “env”. You can set the environment parameter by setting the required environment value to window.MafPay.env, the possible values are:
environment | value |
---|---|
Sandbox | sandbox |
Production | production |
window.MafPay = {
env: sandbox
}
Using 3DS Component
The component can be used anywhere on the checkout page by declaring its tag as below.
<mafpay-threeds-component threedsauthid=“<your 3DS authentication ID>“></mafpay-threeds-component>
Events
MAF Pay provides callback event to receive the status of the payment or tokenization transactions, the callback is as below:
element.addEventListener('processComplete', event => {
console.log('Processing response event ', event.detail);
})
Google Pay
Google Pay is a digital wallet platform that empowers customers to make online purchases securely without entering their card details for each payment. When the customer selects to pay using Google Pay in-app or on the web, Google Pay displays a pop-up dialog that allows customers to choose the card they want to use and confirm the payment.
Setup the environment
To setup the correct environment you can use the environment parameter “env”. You can set the environment parameter by setting the required environment value to window.MafPay.env, the possible values are:
MAF Pay Google Pay component provides a simplified way to include Google Pay in your checkout page.
environment | value |
---|---|
Sandbox | sandbox |
Production | production |
Using Google Pay button Component
The component can be used anywhere on the checkout page by declaring its tag as below.
<mafpay-google-pay-button token="Checkout Token" merchant-id="Your merchant Id from Google Pay business console"></mafpay-google-pay-button>
Component Properties
Property | Description | Type | Default |
---|---|---|---|
token | The token generated by MAF Pay checkout API. This prop is required. | string | undefined |
merchant-id | Your merchant Id from google pay business console. (Please note that this step is not required in the testing phase). | string | undefined |
button-color | Please check Google Pay customization guide for more details. | string | 'default' |
button-type | Please check Google Pay customization guide for more details. | string | 'buy' |
enable-button-loading | This attribute will enable the default loading that appears before adding the GooglePay button to the page. | boolean | true |
enable-processing-loading | This attribute will enable the default loading that appears after confirming the payment. | boolean | true |
Events
MAF Pay provides three callback events to receive the status of the payment transactions using GooglePay, the callbacks are as below:
Event | Description |
---|---|
googlePayClose | Triggers when the customer closes the Google Pay payment sheet. This does not mean that the user completed the payment flow. It can be useful to indicate customer behavior. |
googlePayCompleted | This indicates that the checkout session has reached a terminating state (either success or failure) using Google Pay button. The final results can be retrieved from the server-to-server feedback. |
googlePayError | Triggers whenever an error occurs within the payment flow. |
loadingEvent | Triggers when start/finish loading the component to show the button to the page. You will receive { isLoading: true } when starting the loading and { isLoading: false } when finishing the loading. |
processingLoadingEvent | Triggers when start/finish processing the payment. You will receive { isLoading: true } when confirming the payment and start processing it and { isLoading: false } when finish processing the payment. |
Note: To be able to test the GooglePay locally, you need to run your HTML page on a local server on your machine like (Apache Tomcat, Nginx, or any server).
Apple Pay
Before you start, you’ll need to be enrolled in the Apple Developer Program and create a payment certificate from Setup ApplePay section. Next, register and verify the merchant domains in your organization that will process the Apple Pay transactions, then create a merchant identity certificate that you’ll use to authenticate communication with the Apple Pay servers.
Setup the environment
To setup the correct environment you can use the environment parameter “env”. You can set the environment parameter by setting the required environment value to window.MafPay.env, the possible values are:
MAF Pay Google Pay component provides a simplified way to include Google Pay in your checkout page.
environment | value |
---|---|
Sandbox | sandbox |
Production | production |
Register and Verify Your Merchant Domain
You must register and verify all top-level domains and subdomains where you will display the Apple Pay button, refer to Apple Pay guide for more details.
Create merchant identity certificate (.pem)
Create a certificate signing request(csr), please refer to the Apple Pay guide for more details.
Note: certificate key pair has to be in RSA 2048 bit formatFrom keychain access app, navigate to keys tab and export the private key of the generated csr, the extension will be .p12, leave the requested export password empty when ask for it.
Convert the exported private key file .p12 to pem file using the following command:
openssl pkcs12 -in (your private key).p12 -out (exported file name).pem -nodes
Note: the generated file is going to be used later in step no.6Form Apple developer account: create merchant identity certificate
steps:- Choose the merchant id that you want to register in our portal
- Navigate to merchant identity certificates section
- Create the merchant identity certificate using the CSR file (from step no.1)
- A new .cer file will be generated
Convert the cer to .pem using the following command:
openssl x509 -inform der -in (your exported cer file from step no.4).cer -out (output file name).pem
Concatenate both the certificate and the private key in one file(.pem) using the following command:
cat certificate.pem privatekey.pem > combined_certificate.pem
Note:certificate.pem
is the file generated in step no.5 andprivatekey.pem
is the file generated in step no.3.privatekey.pem is the file generated form point no.3
Upload the exported file to the MafPay portal along with the payment certificate and merchant id in Apple Pay service settings.
MAF Pay Apple Pay component provides a simplified way to include Apple Pay in your checkout page.
Using Apple Pay button Component
The component can be used anywhere on the checkout page by using the below tag
<mafpay-apple-pay-button token="Checkout Token"></mafpay-apple-pay-button>
Component Properties
Property | Description | Type | Default |
---|---|---|---|
token | The token generated by MAF Pay checkout API. This prop is required. | string | undefined |
button-style | Please check Apple Pay on web guide for more details. | string | 'black' |
button-type | Please check Apple Pay on web guide for more details. | string | 'buy' |
total-amount-label | The total amount label that will be shown inside Apple Pay pop-up dialog. | string | 'Total' |
Events
Apple Pay component provides callback events to receive the status of the payment transactions:
Event | Description |
---|---|
applePayClosed | Triggers when the customer closes the Apple Pay pop-up dialog. This does not mean that the user completed the payment flow. It can be useful to indicate customer behavior. |
applePayCompleted | This indicates that the checkout session has reached a terminating state (either success or failure) using Apple Pay button. The final results can be retrieved from the server-to-server feedback. |
applePayError | Triggers whenever an error occurs within the payment flow. |
loadingEvent | Triggers when start/finish loading the component to show the button to the page. You will receive { isLoading: true } when starting the loading and { isLoading: false } when finishing the loading. |
Bank Transfer
Link Bank
In order for your customer to be able to make payment using bank transfer, first they need to authorise their bank to transfer funds from their account to your account. Your bank account will be added as a "Beneficiary". For some banks, creating a beneficiary can have a cool-down period of up to 24 hours.
Setup the environment
To setup the correct environment you can use the environment parameter “env”. You can set the environment parameter by setting the required environment value to window.MafPay.env, the possible values are:
environment | value |
---|---|
Sandbox | sandbox |
Production | production |
Using Link Bank Component You can use the following component on your site to allow customers to link their banks:
<mafpay-link-bank merchant-id="Your merchant id" api-key="Your api key" account-holder-id="Account holder id"></mafpay-link-bank>
Component Properties
Property | Description | Type | Default |
---|---|---|---|
merchant-id | The unique identifier assigned for your account. This prop is required. | string | undefined |
api-key | A unique identifier that is used to authenticate requests associated with your account. This prop is required. | string | undefined |
bank-token | An allies to be used as a token instead of generating a random one. This prop is optional | string | undefined |
account-holder-id | The account holder ID that the bank token will be linked to. | string | undefined |
enable-loading | This attribute will enable the default loading that appears before loading the component | boolean | true |
auth0-token | Used to pass auth0-token instead of api-key and account-holder-id properties. | string | undefined |
Events
Event | Description |
---|---|
linkBankCompleted | Triggers when the user finishes the flow successfully, You will receive the bankToken that can be used to complete the checkout sessions |
linkBankClosed | Triggers when the flow is closed by the user |
linkBankError | Triggers when the user receives an error during the flow |
linkBankLoading | Triggers when start/finish loading the component. You will receive { isLoading: true } when starting the loading and { isLoading: false } when finishing the loading. |
Payment
In this step, the customer will confirm the amount they want to transfer from their account to your account. MAF Pay provides bank transfer payment through checkout session component. Once payment initiation has been completed, you will receive the payment status on your feedback URL configured on MAF pay portal.
Setup the environment
To setup the correct environment you can use the environment parameter “env”. You can set the environment parameter by setting the required environment value to window.MafPay.env, the possible values are:
environment | value |
---|---|
Sandbox | sandbox |
Production | production |
Using Link Bank Transfer Component You can use the following component on your checkout page to enable bank transfer payments:
<mafpay-bank-transfer checkout-token="Checkout token" bank-token="Bank token"></mafpay-bank-transfer>
Component Properties
Property | Description | Type | Default |
---|---|---|---|
checkout-token | The checkout session token which is required to complete the payment | string | undefined |
bank-token | The bankToken that generated from the previous step when linking the bank | string | undefined |
enable-loading | This attribute will enable the default loading that appears before loading the component | boolean | true |
Events
Event | Description |
---|---|
bankTransferCompleted | Triggers when the user finishes the flow successfully. |
bankTransferClosed | Triggers when the flow is canceled by the user |
bankTransferError | Triggers when the user receives an error during the flow |
bankTransferLoading | Triggers when start/finish loading the component. You will receive { isLoading: true } when starting the loading and { isLoading: false } when finishing the loading. |
Beacon Terminal
Request Authorization/Pay
Transaction Flow
- The customer walks into a store accepting beacon payments on terminals.
- The customer selects the items/services then proceeds to the cashier to pay using his mobile wallet app.
- The cashier selects sale transaction from the terminal, then cashier enters the transaction amount on the terminal.
- The terminal initiates a new request to the terminal provider backend system to process new payment request, the request contains the transaction details.
- The terminal provider system sends a new request to MAF Pay system including the amount and a unique reference. MAF Pay system validates the received parameters, if all parameters, store, and terminal are valid MAF Pay system initiates new payment request.
- Once the terminal provider system receives the payment request response, it will pass it to the terminal to display the corresponding message.
- The terminal will display a message indicating that the customer should tap his mobile.
- The customer opens his mobile wallet app then clicks on pay and tap his mobile to the beacon.
- The app initiates a new authorization/pay request to process the payment request.
- MAF Pay system receives authorization/pay request, it starts validating the request details. if the payment details is invalid it sends an invalid request code error message to the terminal provider system and the customer.
- Payment details is valid, MAF Pay system submits the payment request to the payment processor.
- After MAF Pay system receives the payment result from the payment processor, it notifies the terminal provider system of the payment result, and returns the payment result to the mobile wallet app to inform the customer
Gateway URL
environment | URL |
---|---|
Sandbox | https://terminal.sandbox.mafpayments.com/api |
Production | https://terminal.mafpayments.com/api |
Note: The Sandbox API is available for integration and compatibility testing of new features before having available on the production environment.
Authentication
To make REST API calls, include the basic authentication in the Authorization header with the basic authentication scheme.
Additionally, you need to include the IntegratorId value of your account in the request header.
Note: MAF Pay will provide you with the account credentials necessary to simulate test payment request.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
Integrator-Id: YourTestingIID
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, for authorization the value is “requestAuth” and for purchase the value is “requestPay” | None | Yes | 30 | A |
integratorReference | The identifier for each transaction. The integrator is responsible for generating this reference. This reference will be printed on the receipts. | None | Yes | 70 | AN |
terminalId | The device unique terminal ID. | _ , - | Yes | 70 | AN |
terminalMid | The MID assigned to the terminal. | - , _ | No | 70 | AN |
amount | A positive integer representing the transaction amount. | None | Yes | 9 | N |
currency | ISO 3166 Alpha-3 code | None | Yes | 3 | A |
extraData | A metadata parameter that can be used to attach specific values to a transaction, you will receive this parameter as part of the response with the same values. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “requestAuth”. | 30 | A |
integratorReference | The identifier for each transaction. The integrator is responsible for generating this reference. This reference will be printed on the receipts. | 70 | AN |
settlementReference | The unique reference generated by MAF Pay system for the transaction. Which will be used for settlement. | 70 | AN |
terminalId | The device unique terminal ID. | 70 | AN |
terminalMid | The MID assigned to the terminal. | 70 | AN |
amount | A positive integer representing the transaction amount. | 9 | A |
qrCodeData | The string representation of the generated QR code | 4000 | AN |
currency | ISO 3166 Alpha-3 code | 3 | A |
extraData | A metadata parameter that can be used to attach specific values to a transaction, you will receive this parameter as part of the response with the same values. | 200 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 200 | AN |
Request Cancel
Transaction Flow
- Cashier wants to cancel the payment request, he clicks on cancel button shown on the terminal screen.
- The terminal initiates a new request to the terminal provider backend system to process a new cancel request, the request contains the original integrator reference submitted during the generation of the payment request.
- The terminal provider system sends cancel request to MAF Pay system including the original transaction reference as part of the cancel request.
- MAF Pay system validates the received parameters, if the request is valid MAF Pay cancels the payment request, and the terminal will receives the final result of the cancel request
Gateway URL
Environment | URL |
---|---|
Sandbox | https://terminal.sandbox.mafpayments.com/api |
Production | https://terminal.mafpayments.com/api |
Note: The Sandbox API is available for integration and compatibility testing of new features before having available on the production environment.
Authentication
To make REST API calls, include the basic authentication in the Authorization header with the basic authentication scheme.
Additionally, you need to include the IntegratorId value of your account in the request header
Note: MAF Pay will provide you with the account credentials necessary to simulate test payment request.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
IntegratorId: YourTestingIID `
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “requestCancel”. | None | Yes | 30 | A |
integratorReference | The identifier for each transaction. The integrator is responsible for generating this reference. This reference will be printed on the receipts. | None | Yes | 70 | AN |
terminalId | The device unique terminal ID. | _ , - | Yes | 70 | AN |
terminalMid | The MID assigned to the terminal. | - , _ | No | 70 | AN |
extraData | A metadata parameter that can be used to attach specific values to a transaction, you will receive this parameter as part of the response with the same values. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “requestCancel”. | 30 | A |
integratorReference | The identifier for each transaction. The integrator is responsible for generating this reference. This reference will be printed on the receipts. | 70 | AN |
terminalId | The device unique terminal ID. | 70 | AN |
terminalMid | The MID assigned to the terminal. | 70 | AN |
extraData | A metadata parameter that can be used to attach specific values to a transaction, you will receive this parameter as part of the response with the same values. | 200 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 200 | AN |
QR Code Terminal
Request Authorization/Pay
Transaction Flow
- The customer walks into a store accepting QR code payments on terminals.
- The customer selects the items/services then proceeds to the cashier to pay using his mobile wallet app.
- The cashier selects QR code sale transaction from the terminal, then cashier enters the transaction amount on the terminal.
- The terminal initiates a new request to the terminal provider backend system to acquire new QR code, the request contains the transaction details.
- The terminal provider system sends a new request to MAF Pay system including the amount and a unique reference. MAF Pay system validates the received parameters, if all parameters, store, and terminal are valid MAF Pay system generates the QR code data according to “EMVCo merchant presented QR specifications”.
- Once the terminal provider system receives the QR code data, it passes the generated QR code data to the terminal.
- The terminal generates the QR code image based on MAF Pay QR code data, then the terminal will displays the QR code on its screen so that the customer is able to scan it of the terminal’s screen.
- The customer opens his mobile wallet app then clicks on scan QR code. The app starts the camera for the customer to scan the QR code of the terminal screen.
- The mobile wallet app displays to the customer the transaction details for his/her confirmation. Once the customer confirms the payment transaction details, the app initiates a new authorization/pay request to process the scanned QR code.
- MAF Pay system receives authorization/pay request, it starts validating the QR code data to make sure the correct QR code is being processed. if the QR code is invalid it sends an invalid QR code error message to the terminal provider system and the customer.
- QR code is valid, MAF Pay system submits the payment request to the payment processor.
- After MAF Pay system receives the payment result from the payment processor, it notifies the terminal provider system of the payment result, and returns the payment result to the mobile wallet app to inform the customer.
Gateway URL
environment | URL |
---|---|
Sandbox | https://terminal.sandbox.mafpayments.com/api |
Production | https://terminal.mafpayments.com/api |
Note: The Sandbox API is available for integration and compatibility testing of new features before having available on the production environment.
Authentication
To make REST API calls, include the basic authentication in the Authorization header with the basic authentication scheme. Additionally, you need to include the IntegratorId value of your account in the request header.
Note: MAF Pay will provide you with the account credentials necessary to simulate test QR code request.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
IntegratorId: YourTestingIID
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, for authorization the value is “requestAuth” and for purchase the value is “requestPay” | None | Yes | 30 | A |
integratorReference | The identifier for each transaction. The integrator is responsible for generating this reference. This reference will be printed on the receipts. | None | Yes | 70 | AN |
terminalId | The device unique terminal ID. | _ , - | Yes | 70 | AN |
terminalMid | The MID assigned to the terminal. | - , _ | Yes | 70 | AN |
amount | A positive integer representing the transaction amount. | None | Yes | 9 | N |
currency | ISO 3166 Alpha-3 code | None | Yes | 3 | A |
extraData | A metadata parameter that can be used to attach specific values to a transaction, you will receive this parameter as part of the response with the same values. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “requestAuth”. | 30 | A |
integratorReference | The identifier for each transaction. The integrator is responsible for generating this reference. This reference will be printed on the receipts. | 70 | AN |
settlementReference | The unique reference generated by MAF Pay system for the transaction. Which will be used for settlement. | 70 | AN |
terminalId | The device unique terminal ID. | 70 | AN |
terminalMid | The MID assigned to the terminal. | 70 | AN |
amount | A positive integer representing the transaction amount. | 9 | A |
currency | ISO 3166 Alpha-3 code | 3 | A |
extraData | A metadata parameter that can be used to attach specific values to a transaction, you will receive this parameter as part of the response with the same values. | 200 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 200 | AN |
qrCodeData | The string representation of the generated QR code. | 4000 | AN |
Request Refund
- The customer walks into a store and proceeds to the cashier to return purchased items or cancel service(s) asking for refund.
- The cashier selects QR code refund, and enters the refund amount and the original transaction reference.
- The terminal initiates a new request to the terminal provider backend system to acquire a new refund QR code, the request contains the refund request details.
- The terminal provider system sends refund request to MAF Pay system including refund amount original transaction reference as part of the refund request. MAF Pay system validates the received parameters, if the request is valid MAF Pay system generates the QR code data according to “EMVCo merchant presented QR specifications”.
- Once the terminal provider system receives the QR code data, it passes the generated QR code data to the terminal.
- The terminal generates the QR code image based on MAF Pay QR code data, then the terminal will displays the QR code on its screen so that the customer is able to scan it of the terminal’s screen.
- The customer opens his mobile wallet app then clicks on refund. The app starts the camera for the customer to scan the QR code of the terminal screen.
- The mobile wallet app displays to the customer the refund transaction details for his/her confirmation. Once the customer confirms the refund transaction details, the app initiates a new refund request.
- MAF Pay system receives refund request, it starts validating the QR code data to make sure the correct QR code is being processed. if the QR code is invalid it sends an invalid QR code error message to the terminal provider system and the customer.
- QR code is valid, MAF Pay system submits the refund request to the payment processor.
- MAF Pay system will start processing the refund by submitting the refund request to the payment processor.
- After MAF Pay system receives the refund result from the payment processor, it notifies the terminal provider system of the refund result, and returns the refund result to the mobile wallet app to inform the customer.
Gateway URL
environment | URL |
---|---|
Sandbox | https://terminal.sandbox.mafpayments.com/api |
Production | https://terminal.mafpayments.com/api |
Note: The Sandbox API is available for integration and compatibility testing of new features before having available on the production environment.
Authentication
To make REST API calls, include the basic authentication in the Authorization header with the basic authentication scheme. Additionally, you need to include the IntegratorId value of your account in the request header.
Note: MAF Pay will provide you with the account credentials necessary to simulate test QR code request.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
IntegratorId: YourTestingIID
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “requestRefund”. | None | Yes | 30 | A |
integratorReference | The identifier for each transaction. The integrator is responsible for generating this reference. This reference will be printed on the receipts. | None | Yes | 70 | AN |
settlementReference | The unique reference generated by MAF Pay system for the transaction. Which will be used for settlement. | None | Yes | 70 | AN |
terminalId | The device unique terminal ID. | _ , - | Yes | 70 | AN |
terminalMid | The MID assigned to the terminal. | - , _ | Yes | 70 | AN |
amount | A positive integer representing the transaction amount. | None | Yes | 9 | N |
extraData | A metadata parameter that can be used to attach specific values to a transaction, you will receive this parameter as part of the response with the same values. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “requestRefund”. | 30 | A |
integratorReference | The identifier for each transaction. The integrator is responsible for generating this reference. This reference will be printed on the receipts. | 70 | AN |
settlementReference | The unique reference generated by MAF Pay system for the transaction. Which will be used for settlement. | 70 | AN |
terminalId | The device unique terminal ID. | 70 | AN |
terminalMid | The MID assigned to the terminal. | 70 | AN |
amount | A positive integer representing the transaction amount. | 9 | N |
extraData | A metadata parameter that can be used to attach specific values to a transaction, you will receive this parameter as part of the response with the same values. | 200 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 200 | AN |
qrCodeData | The string representation of the generated QR code. | 4000 | AN |
Request Void
Gateway URL
environment | URL |
---|---|
Sandbox | https://terminal.sandbox.mafpayments.com/api |
Production | https://terminal.mafpayments.com/api |
Note: The Sandbox API is available for integration and compatibility testing of new features before having available on the production environment.
Authentication
To make REST API calls, include the basic authentication in the Authorization header with the basic authentication scheme. Additionally, you need to include the IntegratorId value of your account in the request header.
Note: MAF Pay will provide you with the account credentials necessary to simulate test QR code request.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
IntegratorId: YourTestingIID
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “requestVoid”. | None | Yes | 30 | A |
integratorReference | The identifier for each transaction. The integrator is responsible for generating this reference. This reference will be printed on the receipts. | None | Yes | 70 | AN |
settlementReference | The unique reference generated by MAF Pay system for the transaction. Which will be used for settlement. | None | Yes | 70 | AN |
terminalId | The device unique terminal ID. | _ , - | Yes | 70 | AN |
terminalMid | The MID assigned to the terminal. | - , _ | Yes | 70 | AN |
extraData | A metadata parameter that can be used to attach specific values to a transaction, you will receive this parameter as part of the response with the same values. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “requestVoid”. | 30 | A |
integratorReference | The identifier for each transaction. The integrator is responsible for generating this reference. This reference will be printed on the receipts. | 70 | AN |
settlementReference | The unique reference generated by MAF Pay system for the transaction. Which will be used for settlement. | 70 | AN |
terminalId | The device unique terminal ID. | 70 | AN |
terminalMid | The MID assigned to the terminal. | 70 | AN |
extraData | A metadata parameter that can be used to attach specific values to a transaction, you will receive this parameter as part of the response with the same values. | 200 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 200 | AN |
Request Cancel
Transaction Flow
- Cashier wants to cancel the payment request, he clicks on cancel button shown on the terminal screen.
- The terminal initiates a new request to the terminal provider backend system to process a new cancel request, the request contains the original integrator reference submitted during the generation of the payment request.
- The terminal provider system sends cancel request to MAF Pay system including the original transaction reference as part of the cancel request.
- MAF Pay system validates the received parameters, if the request is valid MAF Pay cancels the generated QR code, and the terminal will receives the final result of the cancel request
Gateway URL
Environment | URL |
---|---|
Sandbox | https://terminal.sandbox.mafpayments.com/api |
Production | https://terminal.mafpayments.com/api |
Note: The Sandbox API is available for integration and compatibility testing of new features before having available on the production environment.
Authentication
To make REST API calls, include the basic authentication in the Authorization header with the basic authentication scheme. Additionally, you need to include the IntegratorId value of your account in the request header.
Note: MAF Pay will provide you with the account credentials necessary to simulate test QR code request.
Header Example
Authorization: Basic WEthbzEzOlRlc3RQYXNzWFla
IntegratorId: YourTestingIID
Transaction Request
Parameter Name | Description | Allowed Special Chars | Required | Length | Type |
---|---|---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “requestCancel”. | None | Yes | 30 | A |
integratorReference | The identifier for each transaction. The integrator is responsible for generating this reference. This reference will be printed on the receipts. | None | Yes | 70 | AN |
terminalId | The device unique terminal ID. | _ , - | Yes | 70 | AN |
terminalMid | The MID assigned to the terminal. | - , _ | No | 70 | AN |
extraData | A metadata parameter that can be used to attach specific values to a transaction, you will receive this parameter as part of the response with the same values. | Space , ! , " , # , $ , % , & , ' , ( , ) , * , + , , , - , . , / , : , ; , < , = , > , ? , @ , [ , \ , ] , ^ , _ , { , | , } , ~ | No | 200 | AN |
Transaction Response
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of Pay the command will hold the value “requestCancel”. | 30 | A |
integratorReference | The identifier for each transaction. The integrator is responsible for generating this reference. This reference will be printed on the receipts. | 70 | AN |
settlementReference | The unique reference generated by MAF Pay system for the transaction. Which will be used for settlement. | 70 | AN |
terminalId | The device unique terminal ID. | 70 | AN |
terminalMid | The MID assigned to the terminal. | 70 | AN |
extraData | A metadata parameter that can be used to attach specific values to a transaction, you will receive this parameter as part of the response with the same values. | 200 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 200 | AN |
MAF Pay QR Code Data Specification
MAF Pay possible QR code tags
Below table lists MAF Pay possible QR code tags:
Tag | Description | Example |
---|---|---|
50 | Custom tag: MAF Pay Merchant ID | YourTestingMID12 |
52 | Merchant Category Code | 4111 |
58 | Country Code | AE |
59 | Merchant Name | Costa |
60 | Merchant City | Dubai |
64 | Merchant Information— Language Template | ar |
01 | Merchant Name—Alternate Language | كوستا |
02 | Merchant City—Alternate Language | دبي |
54 | Transaction Amount | 12.74 |
53 | Transaction Currency | 784 |
55 | Tip or Convenience Indicator | 01 |
01 | Bill Number | INV_21324 |
04 | Loyalty Number | SH172679 |
03 | Store Label | 123 |
05 | Reference Label | 312 |
06 | Customer Label | Sub_12 |
07 | Terminal Label | Cashier 1 |
08 | Purpose of Transaction | Coffee |
Sample generated QR code data
QR code data
QR code generated image
In Common
API Responses
Invalid HTTP requests
MAF Pay responds with corresponding response code that provides you with an indication of the request status
Response code | Description |
---|---|
400 | Bad request |
401 | Invalid authorization header |
404 | Invalid URL |
Response Codes
You will receive the payment result via responseCode and responseMessage parameters as part of the payment response for each valid request. The table below list possible response codes and messages:
Response code | Response Message | Arabic Response Message |
---|---|---|
000 | Success | تم بنجاح |
001 | Processing | قيد المعالجة |
002 | Customer eligible | العميل مؤهل |
100 | Command not found | أمر غير موجود |
101 | Invalid partner identifier | معرّف الشريك غير صالح |
102 | Invalid card number | رقم البطاقة غير صالح |
103 | Invalid card holder name | اسم حامل البطاقة غير صالح |
105 | Invalid expiry month | شهر إنتهاء الصلاحية غير صالح |
106 | Invalid expiry year | سنة إنتهاء الصلاحية غير صالح |
104 | Invalid expiry date | تاريخ انتهاء الصلاحية غير صالح |
107 | Invalid security code | رقم التحقق غير صالح |
108 | Invalid merchant identifier | معرّف التاجر غير صالح |
109 | Missing parameter | قيمة بيانات مفقودة |
110 | Invalid extra parameter | قيمة البيانات الإضافية غير صالحة |
111 | Invalid parameter format | تنسيق قيمة البيانات غير صالح |
112 | Order reference already exists | مرجع الطلب موجود مسبقاً |
113 | Transaction still processing | مرجع الطلب موجود مسبقاً |
114 | Invalid card token | رمز البطاقة غير صالح |
115 | Order closed | الطلب مغلق |
116 | Invalid payment route | مسار الدفع غير صالح |
117 | Order reference does not exist | مرجع الطلب غير موجود |
118 | Invalid account holder ID | معرف صاحب الحساب غير صحيح |
119 | Transaction reference already exist | مرجع المعاملة موجود مسبقاً |
120 | Transaction reference does not exist | مرجع المعاملة غير موجود |
121 | You have exceeded the number of allowed attempts to verify your card number. The card has been deleted | لقد تجاوزت عدد المحاولات المسموح بها للتحقق من رقم بطاقتك. تم حذف البطاقة |
122 | Card already verified | تم التحقق من البطاقة |
123 | Invalid integrator identifier | معرفIntegrator غير صالح |
124 | Terminal inactive | Terminal غير نشط |
125 | Qr Generating is disabled for the store | مولد رمز الإستجابة للمتجر معطل |
126 | No deployed terminals found | لم يتم العثور على Terminals تم تنفيذها |
127 | No Integrator Found | لم يتم العثور على Integrator |
128 | No terminal Found | لم يتم العثور على Terminal |
129 | No Integrator settings Found | لم يتم العثور على إعدادات Integrator |
130 | Beacon not found | لم يتم العثور على beacon |
131 | Failed to retrieve beacon | فشل استرداد beacon |
132 | No QR-Code settings found | لم يتم العثور على إعدادات رمز الاستجابة |
133 | Duplicate account holder member id | معرف العضوية لصاحب الحساب مكرر |
134 | Duplicate account holder user id | معرف المستخدم لصاحب الحساب مكرر |
135 | Terminal already registered | Terminal مسجل |
136 | Beacon already deployed | تم تنفيذ الـ Beacon |
137 | Terminal already deployed | تم تنفيذ الـ Terminal |
139 | No Store Found | لم يتم العثور على المتجر |
140 | Cashier not ready yet | أمين الصندوق ليس جاهزًا بعد |
141 | Invalid QR code | رمز الاستجابة غير صحيح |
143 | Couldnt process the transaction for this member | تعتذر، لا يمكن معالجة المعاملة لهذا الحساب |
144 | Failed to confirm card verification | فشل في تأكيد التحقق من البطاقة |
145 | Terminal busy | Terminal مشغول |
146 | Program is not enabled for this store | لم يتم تمكين البرنامج لهذا المتجر |
147 | Invalid verification amount | مبلغ التحقق غير صالح |
148 | LMS operations restricted for that store | عمليات LMS مقيدة لهذا المتجر |
149 | Duplicate terminal orderReference | طلب Terminal مكرر |
150 | Invalid username/password in login | اسم المستخدم / كلمة المرور غير صحيحين في عملية تسجيل الدخول |
151 | Card already exists | البطاقة موجودة مسبقاً |
152 | Conversation cannot be found | لا يمكن العثور على المحادثة |
153 | Conversation cannot be aborted | لا يمكن إلغاء المحادثة |
154 | Contract not found | لا يمكن العثور على العقد |
155 | Contract currency does not match transaction currency | عملة العقد لا تتطابق مع عملة المعاملة |
156 | Contract owner does not match store owner | صاحب العقد لا يتطابق مع صاحب المتجر |
157 | Invalid payment option | خيار الدفع غير صالح |
158 | Service Inactive | الخدمة غير نشطة |
159 | Refund amount exceeds capture amount | المبلغ المسترد يتجاوز المبلغ المحجوز |
160 | Capture amount exceeds authorize amount | المبلغ المحجوز يتجاوز مبلغ التأكيد |
161 | Transaction Expired | انتهت المعاملة |
162 | Operation not allowed | العملية غير مسموح بها |
163 | Refund amount exceeds payment amount | مبلغ الاسترداد يتجاوز مبلغ الدفع |
164 | Checkout session is expired or invalid | معرف عملية الدفع منتهي الصلاحية أو غير صالح |
165 | Transaction already paid | المعاملة مدفوعة بالفعل |
166 | Token expired | رمز عملية الدفع منتهي الصلاحية |
167 | Transaction already processed | تمت معالجة المعاملة بالفعل |
168 | Currency not supported | العملة غير مدعومة |
169 | No program configured for store | |
170 | Redirect URL is not configured | لم يتم إعداد رابط التوجيه |
171 | Duplicate card token | رمز البطاقة موجود مسبقا |
172 | Card expired | بطاقه منتهية الصلاحيه |
173 | Carrefour gift card has insufficient balance | رصيد البطاقة غير كاف |
174 | Settings not found or invalid | لم يتم العثور على إعدادات بطاقة هدايا كارفور |
175 | Currency is not supported | عمله البطاقه غير متطابقه مع الطلب |
176 | Card non-redeemable | لا يمكن الخصم من البطاقه |
177 | Invalid bank token | رمز البنك غير صالح |
178 | Capture amount should be equal to authorize amount | يجب أن يكون المبلغ المقتطع مساويًا للمبلغ المحجوز |
179 | Recurring intent is applicable to threeds card verification only | لتحقق من البطاقة فقط (3DS) الدفعات المجدولة قابلة لتطبيق مع خاصية |
180 | Payment link already processed | تمت معالجة رابط الدفع |
181 | Payment link is still processing | لا يزال رابط الدفع قيد المعالجة |
182 | Payment link has expired | رابط الدفع منتهي الصلاحية |
183 | Payment link is cancelled | تم إلغاء رابط الدفع |
184 | Invalid terminal pin | terminal pin غير صالح |
185 | Not Found | لم يتم العثور |
186 | Invalid expiry date | تاريخ انتهاء الصلاحية غير صالح |
187 | Payment method not active | طريقة الدفع المختارة غير مفعلة |
188 | Payment link setting not found | |
189 | Recurring intent has not been initiated | الدفعات المجدولة لم تبدأ بعد |
190 | Invalid pin code | رمز التحقق غير صالح |
191 | Card blacklisted, too many attempts | تم حظر البطاقة ، عدة محاولات غير ناجحة |
192 | Card blacklisted | تم حظر البطاقة |
500 | Unknown Error | خطأ غير معروف |
501 | Unauthorized | غير مصرح |
600 | Transaction declined | تم رفض العملية |
601 | 3D Secure check failed | فشل التحقق من عملية التأكيد (3D Secure) |
602 | Insufficient funds | تم رفض المعاملة بسبب عدم كفاية الرصيد |
603 | Failed to process transaction | فشل في معالجة المعاملة |
604 | Card authentication failed | فشل تأكيد البطاقة |
605 | Insufficient rewards balance | رصيد المكافآت غير كاف |
606 | Customer not eligible | العميل غير مؤهل |
607 | Failed to check eligibility | فشل التحقق من إمكانية الطلب |
608 | Failed to close transaction | فشل إغلاق العملية |
609 | Reward transaction already reversed | |
630 | Blocked high risk transaction | حظر معاملة عالية المخاطر |
631 | Pending with the bank, requires manual reconciliation | قيد الانتظار مع البنك ، تتطلب إجراء تسوية |
700 | Transaction processed, waiting for bank confirmation. | تمت معالجة المعاملة ، في انتظار تأكيد البنك. |
800 | An error occurred in calling external api | حدث خطأ أثناء استدعاء واجهة برمجة التطبيقات الخارجية |
1000 | User not found | المستخدم ليس موجود |
1001 | Account not found | الحساب غير موجود |
1002 | Account not active | الحساب غير نشط |
1003 | User not active | المستخدم غير نشط |
1004 | User already exist | المستخدم موجود مسبقاً |
1005 | Account already exist | الحساب موجود مسبقاً |
1010 | Max amount limit exceeded | تجاوز الحد الأقصى للمبلغ |
1011 | Max frequency amount limit exceeded | تم تجاوز الحد الأقصى لمقدار المحاولات |
1012 | Minimum Balance reached | تم الوصول إلى الحد الأدنى للرصيد |
1013 | Maximum Balance reached | تم بلوغ الحد الأقصى للرصيد |
1030 | Card verification applies to saved cards only | يتم التحقق من البطاقة في حال كانت مخزنة فقط |
Server Notification System
Server Notifications are messages sent from the MAF Pay system to your server system. They push information about payment status changes along with other details as soon as they are available, so that your system is always up to date.
Setting up notifications
a.Log in to the Partner Administration Portal (PAP)
b.Click “Integration settings” from the left menu.
c.Under Server Notification section, fill the “Notification URL” field with your desired API URL that you wish to receive the notifications.
Acknowledging Notification Receipt
To acknowledge receipt of a notification, you must respond within 30 seconds with the following:
d. HTTP status code 200
e. "[OK]" in the response body
Any non-200 status code will be treated as a failure.
Notifications Parameters
Parameter Name | Description | Length | Type |
---|---|---|---|
command | The operation name requested, in case of Pay@Terminal. the command will hold the value “payAtTerminal”. | 30 | A |
orderReference | The unique reference for each transaction. The integrator is responsible for generating this reference. This reference will be printed on the receipts. | 70 | AN |
terminalId | The terminal identifier assigned. | 30 | AN |
transactionId | The unique reference generated by MAF Pay system for the transaction. | 70 | AN |
amount | A positive integer representing the transaction amount. | 9 | N |
rewardAmount | A positive integer representing the reward amount deducted from the customer. | 9 | N |
cardAmount | A positive integer representing the card amount deducted from the customer. | 9 | N |
currency | Three-letter ISO currency code | 3 | A |
extraData | A metadata parameter that can be used to attach specific values to a transaction, you will receive this parameter as part of the response with the same values. | 200 | AN |
responseCode | A code represents the result of the transaction processing. | 3 | N |
responseMessage | A text that describes the result of the transaction processing. | 200 | AN |
authCode | Identifier for this transaction. | 10 | AN |
Response Validation
To validate the response authenticity MAF Pay provides two types based on the way response received either Server-to-Server notifications (Push messages) or redirection response.
Server-to-Server Notifications
For the server to server notifications, MAF Pay supports a secret key authentication that allows merchants to validate the requester by the secret key value submitted in the request.
MAF Pay will include the secret key in a request header parameter called "X-Feedback-Secret", the value is a string of length of 32 characters generated by MAF Pay.
Example:
X-Feedback-Secret: DY6VftX5tM43pTF9W9uLM2BNTRrf4T7E
Redirection Response
Since redirection messages reach the clients devices MAF Pay system supports signature mechanism to validate the authenticity and data integrity.
The steps below describe how to calculate the signature to validate the value of mafpaySignature parameter:
1- Sort all response parameters in an ascending alphabetical order based on the names of the parameter.
2- Concatenate the parameter name with the value separated by '=' (param_name=param_value).
3- Concatenate all the parameters (param_name1=param_value1param_name2=param_value2).
4- Add the Merchant's Passphrase at the beginning and end of the parameters string. (PASSPHRASEparam_name1=param_value1param_name2=param_value2PASSPHRASE).
5- Use the hash-based message authentication code (HMAC) with the SHA256 function to generate the base64 encoded signature value of the resulted string.
Note: You have to URL decode the response returned before start validating MAF Pay signature.
Example:
Sample MAF Pay Response
responseCode=000
responseMessage=Success
authCode=034498
gatewayId=16085535962268780155
cardToken=T16085445975416255897
command=pay
amount=15
currency=AED
orderReference=hussein7179
eci=ecommerce
transactionReference=Tr7179
category=retail
mafpaySignature=d7ojVi0/kZrsWV7IE6qk1hp26RiG6EkM7kbPbunUDEc=
To validate the response above we will go through the steps above:
1- Sort response parameters:
amount=15
authCode=034498
cardToken=T16085445975416255897
category=retail
command=pay
currency=AED
eci=ecommerce
gatewayId=16085535962268780155
orderReference=hussein7179
responseCode=000
responseMessage=Success
transactionReference=Tr7179
2- Adding '=' between the parameter name and value
amount=15
authCode=034498
cardToken=T16085445975416255897
category=retail
command=pay
currency=AED
eci=ecommerce
gatewayId=16085535962268780155
orderReference=hussein7179
responseCode=000
responseMessage=Success
transactionReference=Tr7179
3- Concatenate all parameters:
amount=15authCode=034498cardToken=T16085445975416255897category=retailcommand=paycurrency=AEDeci=ecommercegatewayId=16085535962268780155orderReference=hussein7179responseCode=000responseMessage=SuccesstransactionReference=Tr7179
4- Adding merchant passphrase:
123456789amount=15authCode=034498cardToken=T16085445975416255897category=retailcommand=paycurrency=AEDeci=ecommercegatewayId=16085535962268780155orderReference=hussein7179responseCode=000responseMessage=SuccesstransactionReference=Tr7179123456789
5- Calculate the base64 encoded signature using the HMAC-SHA256 algorithm
d7ojVi0/kZrsWV7IE6qk1hp26RiG6EkM7kbPbunUDEc=
6- Match the value from the MAF Pay response and the generated value from the steps above both values should match, otherwise, the response body is not valid
Testing Data
Credit cards
The table below lists the test cards you can use to simulate test transactions necessary to complete the integration
3D Secure 1
Brand | Number | Expiry Date | Card Security Code | 3D Secure Enrolled |
---|---|---|---|---|
Mastercard | 5123450000000008 | Any | Any | Yes |
Visa | 4242424242424242 | Any | Any | Yes |
Mastercard | 5111111111111118 | Any | Any | No |
Visa | 4005550000000001 | Any | Any | No |
3D Secure 2
Brand | Number | Expiry Date | Card Security Code | Authentication Status |
---|---|---|---|---|
Visa | 4456530000001005 | Any | Any | Successful Frictionless |
Mastercard | 5200000000001005 | Any | Any | Successful Frictionless |
Amex | 376000000000006 | Any | Any | Successful Frictionless |
Visa | 4456530000001096 | Any | Any | Successful Challenge |
Mastercard | 5200000000001096 | Any | Any | Successful Challenge |
Amex | 377400111111115 | Any | Any | Successful Challenge |
Visa | 4456530000001104 | Any | Any | Unsuccessful |
Mastercard | 5200000000001104 | Any | Any | Unsuccessful |
Amex | 371111111111114 | Any | Any | Unsuccessful |
To simulate response codes using the amount:
Amount | Gateway Response Code | Gateway Response Message |
---|---|---|
Any | 000 | Success |
255 | 700 | Transaction processed, waiting for bank confirmation |
256 | 600 | Transaction Declined |
257 | 602 | Transaction declined due to insufficient funds |
To simulate response codes using the card number:
Card Number | Gateway Response Code | Gateway Response Message |
---|---|---|
5506900140200105 | 600 | Transaction Declined |
5506900140100503 | 700 | Transaction processed, waiting for bank confirmation |
Apple Pay
This Link will get you access to the ApplePay Test cards.
Tabby
The details below lists the test customer account you can use to simulate test transactions necessary to complete the integration.
UAE and KSA
Positive flow:
- Email: card.success@tabby.ai
- Mobile Number: +971500000001
- OTP: 8888
- Card: 4111111111111111 and any future date/cvv
Negative flow:
- Email: otp.rejected@tabby.ai
- Mobile Number: +971500000001
- OTP: 8888
- Card: 4111111111111111 and any future date/cvv
For Kuwait use mobile number +96590000001, rest details will be the same as above.
Tamara
The details below lists the test customer account you can use to simulate test transactions necessary to complete the integration.
UAE and KSA
Positive flow:
- Mobile Number: Any valid UAE or KSA number 9 digits starting with 5
- Card: 4242 4242 4242 4242 and any future date
- Cvv : 100
For Kuwait use mobile number +96555000111, rest details will be the same as above.
Bank Transfer
The table below lists the test users you can use to simulate bank transfer use-cases:
- OTP: The user will be asked for an OTP that their bank sent to their mobile phone. For our mock bank, the OTP will always be "1111".
- Security question: The user will be asked to answer a security question that they have previously submitted to the bank. For our mock bank, we have made the questions and answers easy and obvious but in the real world, only your users will know the answer.
- Instant activation: In this scenario the customer links the bank account and it's instantly verified. If the account is not flaged as instant activation, there will be a cool-off period of 15 minutes before the user can make a payment.
Username | Password | OTP | Security question | Instant activation |
---|---|---|---|---|
magdalenelockman | lzzEftQmOiW | No | No | Yes |
denniswolff | cZGUCuYX | Yes | No | Yes |
reidhintz | UXWGzBjzlDmh | No | Yes | Yes |
marcelwintheiser | nZeqiordORhdcB | No | No | No |