Areeba Gateway Integration

Step 1

Step 2

Step 3

Step 4

Step

Prerequisites

Your login credentials will be provided to you when you are successfully boarded onto the gateway.

To make succcessful API requests, you need to generate an API password:

Log in to https://epayment.areeba.com/ma with your login credentials.
Navigate to Admin > Integration Settings > Edit.
Click Generate New, and select the Enable Integration Access Via Password box.
This is the API password you will use to authenticate API requests made from your web server to the gateway.
Click Submit.

You must always have at least one password generated and enabled but you may have up to two passwords set up. For security, you should change the password periodically. Only one password must be used for configuring your application, the second one working as a standby for password rolling purposes.

It is recommended that you opt for the Notifications service to receive notifications (email/Webhook) if the payment is successful. The gateway (on behalf of you) can also send email notifications to the payer.

Credit Card

Use the below test card to test your integration.

Card Number:

Expiry Date:

Security Code:

Cardholder Name:

Initiate a Checkout Session

POST

https://epayment.areeba.com/api/rest/version/82/merchant/{YOUR_MERCHANT_ID}/session

Requests to the Transaction API are sent via HTTPS containing a JSON body.

Authentication

The API username and password must be sent as BASIC Authentication in the Authorization header (refer to RFC 7617).

Username and password are concatenated by a : (colon) and the whole string is Base64 encoded.

Username is merchant.anyMerchantID, password is myPassword
Concatenation is merchant.anyMerchantID:myPassword
Base64 encoded: bWVyY2hhbnQuYW55TWVyY2hhbnRJRDpteVBhc3N3b3Jk
The passed header will then look like this: Authorization: Basic bWVyY2hhbnQuYW55TWVyY2hhbnRJRDpteVBhc3N3b3Jk

Request Body Sample

                                    { 
                                        "apiOperation": "INITIATE_CHECKOUT", 
                                        "interaction": {
                                            "operation": "PURCHASE",
                                            "merchant": {
                                                "name": "Your merchant name",
                                                "address": {
                                                    "line1": "200 Sample St",
                                                    "line2": "1234 Example Town"
                                                }
                                            }
                                        },
                                        "order": {
                                            "currency": "USD",
                                            "id": "{UNIQUE_ORDER_ID}" ,
                                            "amount": 5,
                                            "description": "ordered goods"
                                        },

                                    }

Response Sample

                                    {
                                        "checkoutMode":"WEBSITE",
                                        "merchant":"{YOUR_MERCHANT_ID}",
                                        "result":"SUCCESS",
                                        "session":{
                                            "id":"SESSION0002511385220L77572249G5",
                                            "updateStatus":"SUCCESS",
                                            "version":"932a042a01"
                                        },
                                        "successIndicator":"3ba502ab88494aa8"
                                    }

Thank you Page

When returning to merchant website (in data-complete callback function)

At this step, make a request to "Retrieve order" and check for the result of payment

GET

https://epayment.areeba.com/api/rest/version/82/merchant/{YOUR_MERCHANT_ID}/order/{YOUR_ORDER_ID};

Response

        {
            "3dsAcsEci": "02",
            "amount": 5.00,
            "authentication": {
                "3ds": {
                    "acsEci": "02",
                    "authenticationToken": "kHyn+7YFi1EUAREAAAAvNUe6Hv8=",
                    "transactionId": "54245fd6-94ed-45d6-a86f-7aeb29d8ffa5"
                }
            },
            "authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
            "authenticationVersion": "3DS2",
            "chargeback": {
                "amount": 0,
                "currency": "USD"
            },
            "creationTime": "2023-06-14T09:41:37.187Z",
            "currency": "USD",
            "description": "ordered goods",
            "device": {
                "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36 Edg/114.0.1823.37",
                "ipAddress": "91.151.236.243"
            },
            "id": "{UNIQUE_ORDER_ID}",
            "lastUpdatedTime": "2023-06-14T09:41:53.294Z",
            "merchant": "{YOUR_MERCHANT_ID}",
            "merchantAmount": 5.00,
            "merchantCategoryCode": "7399",
            "merchantCurrency": "USD",
            "result": "SUCCESS",
            "sourceOfFunds": {
                "provided": {
                    "card": {
                        "brand": "MASTERCARD",
                        "expiry": {
                            "month": "1",
                            "year": "39"
                        },
                        "fundingMethod": "CREDIT",
                        "nameOnCard": "test",
                        "number": "512345xxxxxx0008",
                        "scheme": "MASTERCARD",
                        "storedOnFile": "NOT_STORED"
                    }
                },
                "type": "CARD"
            },
            "status": "CAPTURED",
            "totalAuthorizedAmount": 5.00,
            "totalCapturedAmount": 5.00,
            "totalDisbursedAmount": 0.00,
            "totalRefundedAmount": 0.00,
            "transaction": [
                {
                    "authentication": {
                        "3ds": {
                            "acsEci": "02",
                            "authenticationToken": "kHyn+7YFi1EUAREAAAAvNUe6Hv8=",
                            "transactionId": "54245fd6-94ed-45d6-a86f-7aeb29d8ffa5"
                        },
                        "3ds2": {
                            "3dsServerTransactionId": "1fbb6dec-d185-45b4-94f6-939709a83586",
                            "acsTransactionId": "6bff7e4a-fc47-46a6-875a-e1b4d4e1585e",
                            "directoryServerId": "A999999999",
                            "dsTransactionId": "54245fd6-94ed-45d6-a86f-7aeb29d8ffa5",
                            "methodCompleted": false,
                            "methodSupported": "SUPPORTED",
                            "protocolVersion": "2.1.0",
                            "requestorId": "MAS00001_INT_MPGS_APTEST22220136300",
                            "requestorName": "MPGS TEST",
                            "transactionStatus": "Y"
                        },
                        "acceptVersions": "3DS1,3DS2",
                        "amount": 5.00,
                        "channel": "PAYER_BROWSER",
                        "method": "OUT_OF_BAND",
                        "payerInteraction": "REQUIRED",
                        "purpose": "PAYMENT_TRANSACTION",
                        "redirect": {
                            "domainName": "ap.gateway.mastercard.com"
                        },
                        "time": "2023-06-14T09:41:38.289Z",
                        "version": "3DS2"
                    },
                    "device": {
                        "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36 Edg/114.0.1823.37",
                        "ipAddress": "91.151.236.243"
                    },
                    "merchant": "{YOUR_MERCHANT_ID}",
                    "order": {
                        "amount": 5.00,
                        "authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
                        "chargeback": {
                            "amount": 0,
                            "currency": "USD"
                        },
                        "creationTime": "2023-06-14T09:41:37.187Z",
                        "currency": "USD",
                        "description": "ordered goods",
                        "id": "{UNIQUE_ORDER_ID}",
                        "lastUpdatedTime": "2023-06-14T09:41:53.294Z",
                        "merchantAmount": 5.00,
                        "merchantCategoryCode": "7399",
                        "merchantCurrency": "USD",
                        "status": "CAPTURED",
                        "totalAuthorizedAmount": 0,
                        "totalCapturedAmount": 0,
                        "totalDisbursedAmount": 0,
                        "totalRefundedAmount": 0,
                        "valueTransfer": {
                            "accountType": "NOT_A_TRANSFER"
                        }
                    },
                    "response": {
                        "gatewayCode": "APPROVED",
                        "gatewayRecommendation": "PROCEED"
                    },
                    "result": "SUCCESS",
                    "sourceOfFunds": {
                        "provided": {
                            "card": {
                                "brand": "MASTERCARD",
                                "expiry": {
                                    "month": "1",
                                    "year": "39"
                                },
                                "fundingMethod": "CREDIT",
                                "nameOnCard": "test",
                                "number": "512345xxxxxx0008",
                                "scheme": "MASTERCARD"
                            }
                        },
                        "type": "CARD"
                    },
                    "timeOfLastUpdate": "2023-06-14T09:41:51.157Z",
                    "timeOfRecord": "2023-06-14T09:41:37.203Z",
                    "transaction": {
                        "acquirer": {
                            "merchantId": "{YOUR_MERCHANT_ID}"
                        },
                        "amount": 5.00,
                        "authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
                        "currency": "USD",
                        "id": "trans-287",
                        "stan": "0",
                        "type": "AUTHENTICATION"
                    },
                    "version": "82"
                },
                {
                    "authentication": {
                        "3ds": {
                            "acsEci": "02",
                            "authenticationToken": "kHyn+7YFi1EUAREAAAAvNUe6Hv8=",
                            "transactionId": "54245fd6-94ed-45d6-a86f-7aeb29d8ffa5"
                        },
                        "3ds2": {
                            "dsTransactionId": "54245fd6-94ed-45d6-a86f-7aeb29d8ffa5",
                            "protocolVersion": "2.1.0",
                            "transactionStatus": "Y"
                        },
                        "amount": 5.00,
                        "time": "2023-06-14T09:41:38.289Z",
                        "transactionId": "trans-287",
                        "version": "3DS2"
                    },
                    "authorizationResponse": {
                        "commercialCard": "888",
                        "commercialCardIndicator": "3",
                        "financialNetworkCode": "777",
                        "posData": "1025100006600",
                        "posEntryMode": "812",
                        "processingCode": "003000",
                        "responseCode": "00",
                        "stan": "202337",
                        "transactionIdentifier": "123456789"
                    },
                    "device": {
                        "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36 Edg/114.0.1823.37",
                        "ipAddress": "91.151.236.243"
                    },
                    "gatewayEntryPoint": "CHECKOUT_VIA_WEBSITE",
                    "merchant": "{YOUR_MERCHANT_ID}",
                    "order": {
                        "amount": 5.00,
                        "authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
                        "chargeback": {
                            "amount": 0,
                            "currency": "USD"
                        },
                        "creationTime": "2023-06-14T09:41:37.187Z",
                        "currency": "USD",
                        "description": "ordered goods",
                        "id": "{UNIQUE_ORDER_ID}",
                        "lastUpdatedTime": "2023-06-14T09:41:53.294Z",
                        "merchantAmount": 5.00,
                        "merchantCategoryCode": "7399",
                        "merchantCurrency": "USD",
                        "status": "CAPTURED",
                        "totalAuthorizedAmount": 5.00,
                        "totalCapturedAmount": 5.00,
                        "totalDisbursedAmount": 0.00,
                        "totalRefundedAmount": 0.00
                    },
                    "response": {
                        "acquirerCode": "00",
                        "acquirerMessage": "Approved",
                        "gatewayCode": "APPROVED",
                        "gatewayRecommendation": "NO_ACTION"
                    },
                    "result": "SUCCESS",
                    "sourceOfFunds": {
                        "provided": {
                            "card": {
                                "brand": "MASTERCARD",
                                "expiry": {
                                    "month": "1",
                                    "year": "39"
                                },
                                "fundingMethod": "CREDIT",
                                "nameOnCard": "test",
                                "number": "512345xxxxxx0008",
                                "scheme": "MASTERCARD",
                                "storedOnFile": "NOT_STORED"
                            }
                        },
                        "type": "CARD"
                    },
                    "timeOfLastUpdate": "2023-06-14T09:41:53.294Z",
                    "timeOfRecord": "2023-06-14T09:41:53.225Z",
                    "transaction": {
                        "acquirer": {
                            "batch": 20230614,
                            "date": "0614",
                            "id": "BOAS_S2I",
                            "merchantId": "{YOUR_MERCHANT_ID}",
                            "settlementDate": "2023-06-14",
                            "timeZone": "+0200",
                            "transactionId": "123456789"
                        },
                        "amount": 5.00,
                        "authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
                        "authorizationCode": "202337",
                        "currency": "USD",
                        "id": "1",
                        "receipt": "316509202337",
                        "source": "INTERNET",
                        "stan": "202337",
                        "terminal": "AUDS2I05",
                        "type": "PAYMENT"
                    },
                    "version": "82"
                }
            ]
        }
      {
    "3dsAcsEci": "02",
    "amount": 5.00,
    "authentication": {
        "3ds": {
            "acsEci": "02",
            "authenticationToken": "kHyn+7YFi1EUAREAAAAvNUe6Hv8=",
            "transactionId": "54245fd6-94ed-45d6-a86f-7aeb29d8ffa5"
        }
    },
    "authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
    "authenticationVersion": "3DS2",
    "chargeback": {
        "amount": 0,
        "currency": "USD"
    },
    "creationTime": "2023-06-14T09:41:37.187Z",
    "currency": "USD",
    "description": "ordered goods",
    "device": {
        "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36 Edg/114.0.1823.37",
        "ipAddress": "91.151.236.243"
    },
    "id": "{UNIQUE_ORDER_ID}",
    "lastUpdatedTime": "2023-06-14T09:41:53.294Z",
    "merchant": "{YOUR_MERCHANT_ID}",
    "merchantAmount": 5.00,
    "merchantCategoryCode": "7399",
    "merchantCurrency": "USD",
    "result": "SUCCESS",
    "sourceOfFunds": {
        "provided": {
            "card": {
                "brand": "MASTERCARD",
                "expiry": {
                    "month": "1",
                    "year": "39"
                },
                "fundingMethod": "CREDIT",
                "nameOnCard": "test",
                "number": "512345xxxxxx0008",
                "scheme": "MASTERCARD",
                "storedOnFile": "NOT_STORED"
            }
        },
        "type": "CARD"
    },
    "status": "CAPTURED",
    "totalAuthorizedAmount": 5.00,
    "totalCapturedAmount": 5.00,
    "totalDisbursedAmount": 0.00,
    "totalRefundedAmount": 0.00,
    "transaction": [
        {
            "authentication": {
                "3ds": {
                    "acsEci": "02",
                    "authenticationToken": "kHyn+7YFi1EUAREAAAAvNUe6Hv8=",
                    "transactionId": "54245fd6-94ed-45d6-a86f-7aeb29d8ffa5"
                },
                "3ds2": {
                    "3dsServerTransactionId": "1fbb6dec-d185-45b4-94f6-939709a83586",
                    "acsTransactionId": "6bff7e4a-fc47-46a6-875a-e1b4d4e1585e",
                    "directoryServerId": "A999999999",
                    "dsTransactionId": "54245fd6-94ed-45d6-a86f-7aeb29d8ffa5",
                    "methodCompleted": false,
                    "methodSupported": "SUPPORTED",
                    "protocolVersion": "2.1.0",
                    "requestorId": "MAS00001_INT_MPGS_APTEST22220136300",
                    "requestorName": "MPGS TEST",
                    "transactionStatus": "Y"
                },
                "acceptVersions": "3DS1,3DS2",
                "amount": 5.00,
                "channel": "PAYER_BROWSER",
                "method": "OUT_OF_BAND",
                "payerInteraction": "REQUIRED",
                "purpose": "PAYMENT_TRANSACTION",
                "redirect": {
                    "domainName": "ap.gateway.mastercard.com"
                },
                "time": "2023-06-14T09:41:38.289Z",
                "version": "3DS2"
            },
            "device": {
                "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36 Edg/114.0.1823.37",
                "ipAddress": "91.151.236.243"
            },
            "merchant": "{YOUR_MERCHANT_ID}",
            "order": {
                "amount": 5.00,
                "authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
                "chargeback": {
                    "amount": 0,
                    "currency": "USD"
                },
                "creationTime": "2023-06-14T09:41:37.187Z",
                "currency": "USD",
                "description": "ordered goods",
                "id": "{UNIQUE_ORDER_ID}",
                "lastUpdatedTime": "2023-06-14T09:41:53.294Z",
                "merchantAmount": 5.00,
                "merchantCategoryCode": "7399",
                "merchantCurrency": "USD",
                "status": "CAPTURED",
                "totalAuthorizedAmount": 0,
                "totalCapturedAmount": 0,
                "totalDisbursedAmount": 0,
                "totalRefundedAmount": 0,
                "valueTransfer": {
                    "accountType": "NOT_A_TRANSFER"
                }
            },
            "response": {
                "gatewayCode": "APPROVED",
                "gatewayRecommendation": "PROCEED"
            },
            "result": "SUCCESS",
            "sourceOfFunds": {
                "provided": {
                    "card": {
                        "brand": "MASTERCARD",
                        "expiry": {
                            "month": "1",
                            "year": "39"
                        },
                        "fundingMethod": "CREDIT",
                        "nameOnCard": "test",
                        "number": "512345xxxxxx0008",
                        "scheme": "MASTERCARD"
                    }
                },
                "type": "CARD"
            },
            "timeOfLastUpdate": "2023-06-14T09:41:51.157Z",
            "timeOfRecord": "2023-06-14T09:41:37.203Z",
            "transaction": {
                "acquirer": {
                    "merchantId": "{YOUR_MERCHANT_ID}"
                },
                "amount": 5.00,
                "authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
                "currency": "USD",
                "id": "trans-287",
                "stan": "0",
                "type": "AUTHENTICATION"
            },
            "version": "82"
        },
        {
            "authentication": {
                "3ds": {
                    "acsEci": "02",
                    "authenticationToken": "kHyn+7YFi1EUAREAAAAvNUe6Hv8=",
                    "transactionId": "54245fd6-94ed-45d6-a86f-7aeb29d8ffa5"
                },
                "3ds2": {
                    "dsTransactionId": "54245fd6-94ed-45d6-a86f-7aeb29d8ffa5",
                    "protocolVersion": "2.1.0",
                    "transactionStatus": "Y"
                },
                "amount": 5.00,
                "time": "2023-06-14T09:41:38.289Z",
                "transactionId": "trans-287",
                "version": "3DS2"
            },
            "authorizationResponse": {
                "commercialCard": "888",
                "commercialCardIndicator": "3",
                "financialNetworkCode": "777",
                "posData": "1025100006600",
                "posEntryMode": "812",
                "processingCode": "003000",
                "responseCode": "00",
                "stan": "202337",
                "transactionIdentifier": "123456789"
            },
            "device": {
                "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36 Edg/114.0.1823.37",
                "ipAddress": "91.151.236.243"
            },
            "gatewayEntryPoint": "CHECKOUT_VIA_WEBSITE",
            "merchant": "{YOUR_MERCHANT_ID}",
            "order": {
                "amount": 5.00,
                "authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
                "chargeback": {
                    "amount": 0,
                    "currency": "USD"
                },
                "creationTime": "2023-06-14T09:41:37.187Z",
                "currency": "USD",
                "description": "ordered goods",
                "id": "{UNIQUE_ORDER_ID}",
                "lastUpdatedTime": "2023-06-14T09:41:53.294Z",
                "merchantAmount": 5.00,
                "merchantCategoryCode": "7399",
                "merchantCurrency": "USD",
                "status": "CAPTURED",
                "totalAuthorizedAmount": 5.00,
                "totalCapturedAmount": 5.00,
                "totalDisbursedAmount": 0.00,
                "totalRefundedAmount": 0.00
            },
            "response": {
                "acquirerCode": "00",
                "acquirerMessage": "Approved",
                "gatewayCode": "APPROVED",
                "gatewayRecommendation": "NO_ACTION"
            },
            "result": "SUCCESS",
            "sourceOfFunds": {
                "provided": {
                    "card": {
                        "brand": "MASTERCARD",
                        "expiry": {
                            "month": "1",
                            "year": "39"
                        },
                        "fundingMethod": "CREDIT",
                        "nameOnCard": "test",
                        "number": "512345xxxxxx0008",
                        "scheme": "MASTERCARD",
                        "storedOnFile": "NOT_STORED"
                    }
                },
                "type": "CARD"
            },
            "timeOfLastUpdate": "2023-06-14T09:41:53.294Z",
            "timeOfRecord": "2023-06-14T09:41:53.225Z",
            "transaction": {
                "acquirer": {
                    "batch": 20230614,
                    "date": "0614",
                    "id": "BOAS_S2I",
                    "merchantId": "{YOUR_MERCHANT_ID}",
                    "settlementDate": "2023-06-14",
                    "timeZone": "+0200",
                    "transactionId": "123456789"
                },
                "amount": 5.00,
                "authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
                "authorizationCode": "202337",
                "currency": "USD",
                "id": "1",
                "receipt": "316509202337",
                "source": "INTERNET",
                "stan": "202337",
                "terminal": "AUDS2I05",
                "type": "PAYMENT"
            },
            "version": "82"
        }
    ]
}

Areeba Gateway Integration

Prerequisites

Credit Card

Initiate a Checkout Session

Authentication

Request a Hosted Checkout Interaction

ACS emulator

At this step, just press submit

Thank you Page

When returning to merchant website (in data-complete callback function)

At this step, make a request to "Retrieve order" and check for the result of payment

Areeba Gateway Integration

Prerequisites

Credit Card

Initiate a Checkout Session

Authentication

Request a Hosted Checkout Interaction

ACS emulator

At this step, just press submit

Thank you Page

When returning to merchant website (in data-complete callback function) At this step, make a request to "Retrieve order" and check for the result of payment

When returning to merchant website (in data-complete callback function)

At this step, make a request to "Retrieve order" and check for the result of payment