BENEFIT Gateway
Overview
BENEFIT is a domestic payment network in Bahrain. It acts as a payment gateway for online transactions and supports debit card users of Bahrain. The network enables businesses to accept payments from customers in Bahrain through a secure and convenient online process using debit cards.
For more information, refer to BENEFIT.
Prerequisites
To offer the BENEFIT payment method through the Mastercard Gateway:
- Establish a merchant account with a member bank that participates in the BENEFIT payment gateway. Obtain your BENEFIT merchant ID (MID) and credentials. These details are required to register your domain and CNAME.
- Register with your Mastercard Payment Gateway Service (MPGS) service provider and share your BENEFIT MID, credentials, domain, and CNAME.
- Ask your acquirer to configure your merchant profile on the Mastercard Gateway to enable BENEFIT gateway acceptance.
Contact your local product team for additional support.
BENEFIT payer journey flow
The following stages describe the BENEFIT payer journey:
- Consumers must:
- Select products or services.
- Complete the checkout process.
- Provide basic customer information, such as first name, last name, email address, telephone number, and address details.
- Select BENEFIT as the payment option.
- The browser redirects the consumer to the BENEFIT page.
- The consumer enters card details and authenticates or authorizes the payment.
- The browser redirects the consumer to your page with the final payment status.
If the payment is unsuccessful, the consumer can retry using another payment method.
BENEFIT does not support the AUTHORIZATION and CAPTURE model. It supports only the PAY model.
BENEFIT integration
BENEFIT through direct payment
- Direct payment integration enables you to offer BENEFIT on your checkout page.
- BENEFIT is supported from WS-API version 100 and later.
- Submit an Initiate Browser Payment request where:
sourceOfFunds.browserPayment.type = BENEFITbrowserPayment.operation = PAY
BENEFIT transactions
| Transaction details | Value |
|---|---|
| Payment type | Debit Switch Gateway |
| Supported countries | Bahrain |
| Supported currencies | BHD |
| Supported operations | Purchase (PAY), PARTIAL REFUND, REFUND |
| Refund validity | Refunds cannot be issued after 90 days from the purchase date, as per BENEFIT guidelines. |
| Chargeback | Not applicable |
Specific parameter fields
In addition to the standard fields required in a browser payment request, include the following parameters in the Initiate Browser Payment request for BENEFIT:
| Parameter name | Mandatory or optional | Description |
|---|---|---|
| order.amount | Mandatory | Specifies the transaction amount. |
| order.currency | Mandatory | Specifies the transaction currency. |
| order.notificationUrl | Mandatory | Specifies the notification URL. |
| sourceOfFunds.type | Mandatory | Specifies the source of funds. |
| sourceOfFunds.browserPayment.type | Mandatory | Specifies the browser payment type. |
| browserPayment.operation | Mandatory | Specifies the payment operation. |
Initiate BENEFIT payment request
{
"apiOperation": "INITIATE_BROWSER_PAYMENT",
"billing": {
"address": {
"city": "Edinburgh",
"company": "MPGS",
"country": "BHR",
"stateProvince": "Scotland",
"street": "OceanPoint",
"street2": "OceanDrive",
"postcodeZip": "2000"
}
},
"shipping": {
"address": {
"city": "Edinburgh",
"company": "MPGS",
"country": "BHR",
"stateProvince": "Scotland",
"street": "OceanPoint",
"street2": "OceanDrive",
"postcodeZip": "2000"
}
},
"browserPayment": {
"operation": "PAY",
"returnUrl": "{{remotehost}}/api/documentation/integrationGuidelines/index.html"
},
"customer": {
"account": {
"id": "customerAccount"
},
"dateOfBirth": "xxxx-xx-xx",
"email": "ganesh.xxxxx@mxxxx.com",
"firstName": "Ganexxh",
"lastName": "Sxrxxxxxshi",
"mobilePhone": "07792xxxxx55",
"nationalId": "nationalId1",
"phone": "989xxx9898"
},
"order": {
"reference": "TEST-SUCCEED",
"amount": "1.00",
"currency": "BHD",
"itemAmount": "1.00",
"item": [
{
"detail": {
"unitTaxRate": "0"
},
"name": "Spud",
"quantity": "1",
"unitPrice": "0.5",
"unitTaxAmount": "0.02",
"unitDiscountAmount": "0.03",
"description": "item1 description",
"sku": "item1"
},
{
"detail": {
"unitTaxRate": "0"
},
"name": "item2",
"quantity": "1",
"unitPrice": "0.5",
"unitTaxAmount": "0.02",
"unitDiscountAmount": "0.03",
"description": "item2 description",
"sku": "item2"
}
],
"shippingAndHandlingAmount": "0.02",
"taxAmount": "0.04",
"description": "apmspi test order",
"notificationUrl": "https://pki.mtf.gateway.mastercard.com/callbackInterface/apmspinotification"
},
"sourceOfFunds": {
"browserPayment": {
"type": "BENEFIT_BH"
},
"type": "BROWSER_PAYMENT"
}
}
Initiate BENEFIT payment response
{
"billing": {
"address": {
"city": "Edinburgh",
"company": "MPGS",
"country": "BHR",
"postcodeZip": "2000",
"stateProvince": "Scotland",
"street": "OceanPoint",
"street2": "OceanDrive"
}
},
"browserPayment": {
"interaction": {
"status": "INITIATED",
"timeInitiated": "2025-06-09T07:24:40.466Z"
},
"operation": "PAY",
"redirectHtml": "<div id=\"initiateRedirect\" xmlns=\"http://www.w3.org/1999/html\"><iframe srcdoc=\"<script src='https://drogon.ottu.dev/b/checkout/redirect/start/?session_id=14510b2df35fbe2ebf2546bacdaa195f605cd4e0&pg_code=BENEFIT_BH'>window.top.location.href='https://drogon.ottu.dev/b/checkout/redirect/start/?session_id=14510b2df35fbe2ebf2546bacdaa195f605cd4e0&pg_code=BENEFIT_BH';</script>\" id=\"redirectFrame\" name=\"redirectFrame\" height=\"100%\" width=\"100%\"></iframe></div>",
"returnUrl": "https://mtf.gateway.mastercard.com/api/documentation/integrationGuidelines/index.html"
},
"customer": {
"account": {
"id": "customerAccount"
},
"email": "ganesh.xxxxx@mxx.com",
"firstName": "Ganesh",
"lastName": "Sxxyxxxxxi",
"mobilePhone": "077xxxx5555",
"nationalId": "nationalId1",
"phone": "989xxx9898"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "OTTU_MER1",
"order": {
"amount": 1,
"chargeback": {
"amount": 0,
"currency": "BHD"
},
"creationTime": "2025-06-09T07:24:40.406Z",
"currency": "BHD",
"description": "apmspi test order",
"discount": {
"amount": 0.06
},
"id": "12345146",
"item": [
{
"description": "item1 description",
"detail": {
"unitTaxRate": 0
},
"name": "Spud",
"quantity": 1,
"sku": "item1",
"unitDiscountAmount": 0.03,
"unitPrice": 0.5,
"unitTaxAmount": 0.02
},
{
"description": "item2 description",
"detail": {
"unitTaxRate": 0
},
"name": "item2",
"quantity": 1,
"sku": "item2",
"unitDiscountAmount": 0.03,
"unitPrice": 0.5,
"unitTaxAmount": 0.02
}
],
"itemAmount": 1,
"lastUpdatedTime": "2025-06-09T07:24:47.316Z",
"merchantAmount": 1,
"merchantCurrency": "BHD",
"notificationUrl": "https://pki.mtf.gateway.mastercard.com/callbackInterface/apmspinotification",
"reference": "TEST-SUCCEED",
"shippingAndHandlingAmount": 0.02,
"status": "INITIATED",
"taxAmount": 0.04,
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalDisbursedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"acquirerCode": "ACCEPTED",
"gatewayCode": "SUBMITTED",
"gatewayRecommendation": "NO_ACTION"
},
"result": "SUCCESS",
"shipping": {
"address": {
"city": "Edinburgh",
"company": "MPGS",
"country": "BHR",
"postcodeZip": "2000",
"stateProvince": "Scotland",
"street": "OceanPoint",
"street2": "OceanDrive"
}
},
"sourceOfFunds": {
"browserPayment": {
"type": "BENEFIT_BH"
},
"type": "BROWSER_PAYMENT"
}
}
Interpretation of the transaction result
The following tables explain the possible transaction response codes after initiating a BENEFIT payment.
| Initiate browser payment response | Result | What this means |
|---|---|---|
response.gatewayCode=SUBMITTED |
SUCCESS |
Redirect the payer using the URL provided in the response. |
| Retrieve transaction or Retrieve order response | Result | What this means |
|---|---|---|
response.gatewayCode = APPROVED |
SUCCESS |
The payment is successful. |
response.gatewayCode = PENDING |
PENDING |
The Mastercard Gateway is waiting for a notification from the acquirer about the payment result. Try RETRIEVE_TRANSACTION again later or listen for notifications from the Mastercard Gateway. |
response.gatewayCode = CANCELLED |
FAILURE |
The payer cancelled the interaction for this payment. |
response.gatewayCode = DECLINED or ACQUIRER_SYSTEM_ERROR |
FAILURE |
The payment was declined. Offer the payer to try another payment method. If the response is ACQUIRER_SYSTEM_ERROR, contact the acquirer for the reason or try RETRIEVE_TRANSACTION again. |
response.gatewayCode = TIMED_OUT |
FAILURE |
Treat this as a declined payment. The Mastercard Gateway ensures the transaction is not successful or will revert it. |
BENEFIT through hosted checkout
Hosted Checkout integration enables you to collect payment details from the payer through an interaction hosted and displayed by the gateway.
From API version 100 and later, BENEFIT is automatically available as a payment method once your payment service provider enables and configures it for your account.
For more information, refer to Browser Payments through Hosted Checkout integration.
Webhook notifications
If you subscribe to Mastercard Gateway webhook notifications, you will receive additional updates about the paymentStatus.