Guides
Tarabut Portal

Take a single payment

Suggest Edits

Get started

Taking a single payment as a Partner account follows the same approach as taking a single domestic payment, but uses separate endpoints and additional parameters. Start by familiarising yourself with single payments, including how to request single paymentsand get status updates for single payments.

Once you're familiar with the process, you can recreate the steps with some minor differences.

📘

Helpful to know

To learn more about idempotent requests, please refer here.

You'll need to generate a partner access token. Learn how to do this in the Partner portal here.

Partner payment requests

Create a PIR. Send an HTTP POST request to the relevant endpoint + /api/v1/partners/payments/ including the header Idempotency-Key andAuthorization: Bearer <payment_token>.

In addition to the standard PIR parameters, you must include an additional parameter merchant.

Request

{
  "merchantId": "0ab54f38fb1fcfa9",  	
  "amount": "17.684",
  "currency": "BHD",
  "destinationAccount": "BHD1",
  "description": "Web payment",
  "callbackUrl": "yoursite.com/payment-outcome-page",
  "countries": ["BHR"],
  "customerReference": "P739570946",
  "merchantReference": "76FG7JQ",
  "expiration": {
    "unit": "DAYS",
    "value": 1
    }
}
ParameterDescription
merchant16 digit alphanumeric merchant identifier - used to signify the Merchant account you wish to request payment for.

Response

{
  "redirectUrl": "<redirect_url>",
  "qrCodeUrl": "<qr_code_url>",
  "requestId": "adca2b6a077de1f5",
  "mediaType": "URL"
}

Using partner webhook notifications

The payment status webhook includes an additional merchant parameter in the body to identify the Merchant account the payment relates to.

Response

{
  "type": "PAYMENT_STATUS_CHANGE",
  "merchant": "1f7rhste5rj0unf6",
  "paymentId": "5da26306860bb993",
  "status": "COMPLETED",
  "timestamp": 1632494853092,
  "amount": 1.00,
  "currency": "BHD",
  "description": "Test payment",
  "bankName": "ILA",
  "destinationAccount": "BHD1",
  "creationTimestamp": "2021-09-24T14:47:22.764Z",
  "customerReference": "123",
  "merchantReference": "ABC",
}
ParameterDescription
merchant16 digit alphanumeric merchant identifier of the Merchant account the payment was requested for.

👍

Try it out

Make sure you setup a callback URL in your Partner account to receive webhook notifications for payments made from your account for any linked Merchant accounts.

Using partner payment status calls

You can request a payment status update on any payment at any time by sending an HTTP GET request to the relevant base URL + /api/v1/partners/payments/ including the headers Authorization: Bearer <payment_token>.

Responses will include an additional merchant parameter in the body to identify the Merchant account the payment relates to.

Request

curl --location --request GET 'https://sandbox.payments.tarabutgateway.io/api/v1/partners/payments/<paymentId>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <payment_token>'

Response

{
  "id": "8ff54f54fd1ef8a9",
  "amount": "17.684",
  "currency": "BHD",
  "merchant": "1f7rhste5rj0unf6", 
  "description": "Test payment",
  "status": "COMPLETED",
  "bank": "ILA", 
  "destinationAccount": "BHD1",
  "createdAt": "2021-09-27T11:22:58.203Z",
  "customerReference": "jgdw74jg",
  "merchantReference": "yegdt6t67g",
  "initiator": 'PARTNER',
  "expiryDateZoned": "2022-08-31T17:19:25.533Z"
}
ParameterDescription
merchant16 digit alphanumeric merchant identifier of the Merchant account the payment was requested for.

Updated about 1 month ago