Guides
Tarabut Portal

Request single payment

Suggest Edits

1. Create payment request

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

📘

Helpful to know

To learn more about idempotent requests, please refer here.

You'll need to generate an access token, please refer here.

curl --location --request POST 'https://sandbox.payments.tarabutgateway.io/api/v1/payments'
--header 'Idempotency-Key: <Idempotency_Key>'
--header 'Authorization: Bearer <payment_token>'
--header 'Content-Type: application/json'
--data-raw '{
  	"amount": "10.95",
  	"currency": "BHD",
    "destinationAccount": "BHD1",
  	"description": "Web payment",
    "callbackUrl": "yoursite.com/payment-outcome-page",
    "mediaType": "URL",
    "countries": ["BHR"],
    "customerReference": "123",
    "merchantReference": "ABC",
    "expiration": {
    	"unit": "DAYS",
    	"value": 1
    }
}'
ParameterDescription
amountAmount to be paid.
currencyThe three-character payment currency using ISO 4217. Tarabut support BHD.
destinationAccountSpecifies the ID of the merchant's destination bank account.
descriptionAn internal description - can be up to 250 characters alphanumeric.
callbackUrlThe URL the payer will be redirected back to after the authorisation is completed - can be up to 255 characters.
mediaTypeSpecifies if the response should contain a URL to the payment page or a QR code. Accepted values are QR and URL. Default value is URL.
countriesSpecifies the countries of which banks are available on the bank selection page.
customerReferenceReference field for customer ID - can be up to 128 characters alphanumeric. Optional field.
merchantReferenceReference field for order ID - can be up to 256 characters and alphanumeric.
expirationThe validity duration parameter of the payment (can be set in DAYS, HOURS or MINUTES). Minimum value is 30 minutes and the maximum value is 31 days.

A successful PIR returns a 202 response code and an object.

If something unexpected happened during the request, the API returns an error response with the appropriate HTTP status code and a JSON response that contains detailed information about the problem.

Response

{
  "redirectUrl": "<redirect_url>",
  "qrCodeUrl": "<qr_code_url>",
  "requestId": "adca2b6a077de1f5",
  "mediaType": "URL"
}
ParameterDescription
redirectUrlThe URL of the hosted checkout page to be presented to consumers. This value is returned when mediaType is URL.
qrCodeUrlThe URL of the QR code which encodes the URL of the payment page. This value is returned when mediaType is QR.
requestId16 digit alphanumeric unique payment identifier.
mediaTypeSpecifies the format the payment link was generated. Possible values URL and QR.

🚧

Be aware

If the expiration field was not specified in the Payment Initiation Request the URL and QR code are only valid for 30 minutes after the Payment Initiation Request was created.

2. Bank selection and consent

Redirect your consumer using the URL or QR code provided in the PIR redirectUrl response. For example, use the URL to redirect users in your application, send the URL as a link in an e-mail, or present the QR code for the consumer to scan on their device. Understand more about how the hosted checkout works and its use cases here.

Updated 18 days ago