Authorization2
Learn how to handle authorization requests.
The Authorization request is made when the customer makes a purchase or pays for a service with a card. It handles pre-authorization and capture in one interface. Once the authorization request is sent to the Payment Gateway, the credit card data and the credit line is verified and the cardholder is charged immediately.
The authorization flow for cards includes 3DSecure check by default. Contact your Client Relations manager or Technical support for specific rules for your account.
Endpoint
POST https://sandbox.payabl.com/pay/backoffice/payment_authorize
3Ds flow
-> POST Request to /payment_authorize
<- Response (synchronous) with status=2000 (pending) and URL for 3DS redirect
Redirect Customer to to 3DS URL
Customer completes 3D-Secure process
Customer is redirected to Return URL
<- HTML Response with a final status (success or decline) and 3DS related information
<- Callback (asynchronous) with a final status (success or decline) to notification_url
Non-3Ds flow
-> POST Request to /payment_authorize (add param_3d=non3d to your request to avoid 3DS)
<- Response (direct, synchronous) with a final status (success or decline)
Optional <- Callback (asynchronous) with a final status (success or decline) to notification_url
We don't send callbacks for non-3DS transactions by default. Please contact our Technical support team if you wish to receive them.
For additional information on 3DSecure flow, please refer to 3DSecure Transactions section.
Step 1. Send request
Include in your POST request mandatory parameters listed below. You can see a full list of parameters in Authorization API reference.
For Sandbox environment use these Testing Credentials for Credit Cards
| Parameter | Format | Description |
|---|---|---|
merchantid | 40 characters | Merchant identification number assigned during account creation |
orderid | max. 40 characters | The field orderid is optional and exclusively for the merchants' convenience |
amount | digits only, either no decimals or two decimal places (e.g. 8 or 8.50) | Transaction’s total amount that will be deducted from the customer |
currency | 3 characters. ISO 4217 | The currency field contains the alpha-3 currency code for the transaction. Links to ISO |
payment_method | 1 for credit cards | payabl. Payment methods IDs |
signature | 40 characters | Signature Calculation2 |
ccn | 16-18 digits | Customer's credit card number |
exp_month | 2 digits | Card expiry month |
exp_year | 4 digits | Card expiry year |
cvc_code | 3 digits | Card CVV/CVC code |
cardholder_name | max. 50 characters | Cardholder name |
email | max 50 characters | Customer email. An RFC 822 compliant email address |
customerip | max. 39 characters | Customer IP address |
country | 3 characters. ISO 3166 alpha3 format | Country of customer. Links to ISO |
city | max. 100 characters | The customer's city |
zip | max. 10 characters | The customer's postal code |
street | max. 100 characters | Street of the customer's address |
url_return | max. 255 characters starting with http or https | URL for customer redirection |
shop_url | max. 255 characters starting with http or https | URL of the website from which request is sent (applied if several domains are used for 1 account) |
Request example:
merchantid=gateway_test&orderid=Payabl-Test&amount=19.99¤cy=EUR&payment_method=1&language=en&
customerip=93.109.250.238&[email protected]&firstname=John&lastname=Doe&zip=3035&street=Olympion&house=23&
city=Limassol&country=CYP&ccn=4012001036298889&exp_month=07&exp_year=2028&cvc_code=924&cardholder_name=John Doe&
param_3d=try3d&url_return=https://yourshop.example/thank_you¬ification_url=https://yourshop.example/notification&
signature=b94ef6f6e4915b583d4997aabaa05503f8d50123
Public Sandbox information
Do not use your personal email address, Order ID with sensitive information, real customer details and credit card data in the public Sandbox. For email field you may use [email protected].
Step 2. 3D Secure
payabl. will send a response with url_3ds parameter. The status of the transaction will be pending errorcode=2000.
You need to decode it and redirect the customer. Then client will need to provide PIN/passphrase to their bank/customer’s credit card institution for transaction verification.
Response example:
transactionid=104837274&transid=104837274&status=2000&errormessage=pending&errmsg=pending&amount=19.99&price=19.99&
currency=EUR&orderid=Payabl-Test&user_id=466838&url_3ds=https%3A%2F%2Fpay4.sandbox.payabl.com%2F3dss%2Ftest%2Fv1%2F269
3191992fb30b88ae5d6348293b326%2Fredirect
Response fields reference:
| Parameter | Description |
|---|---|
transactionid | payabl. internal transaction id. Please use this transaction id when referring to the transaction in communications with the payabl. team |
transid | The same as transactionid |
status | Transaction error code |
errormessage | Brief explanation of transaction decline reason (empty on success) |
errmsg | The same as errormessage |
amount | Transaction amount |
price | The same as amount |
currency | Transaction currency |
orderid | Optional transaction identifier given by the merchant |
url_3ds | URL for customer redirection to finalize the payment (URL encoded) |
user_id | Payment system user identifier |
Step 3. Capture response
When the 3DSecure process is complete. payabl. sends a response with a final status:
- HTML response (for a decline) to your side which can be displayed on your return URL.
Response example:
orderid=Payabl-Test&transactionid=105226632&errorcode=-10001&errormessage=3DSecure+verification+failed+or+incomplete&3dProtocolVersion=2.2.0&
3dauthentication_flow=frictionless_flow&3dauthentication_status=R&3dcardholderInformation=Your+cart+requires+additional+verification+contact+your+bank&
3dtransactionStatusReason=12&3dtransactionStatusReasonMessage=Transaction+not+permitted+to+cardholder&type=order&
security=deface93c42747c7ab84e43de5353bfcd8eed4d6
Additional 3DS error information on your Result page
You should include value from the field 3dcardholderInformation to your Return URL page in order to provide more details to your cardholder. This field shows a response directly from the issue on further authentication steps.
The field 3dcardholderInformation is present only in case an Issuer provides this info.
- Callback with the security parameter, which you will need to use in order to verify the authenticity of the notification. Signature Calculation.
Callback example: (for success)
errormessage=&type=capture×tamp=1686139119&3dauthentication_status=Y&orderid=Payabl-Test&3dProtocolVersion=2.2.0&
transactionid=105226633&errorcode=0&3dauthentication_flow=challenge_flow&security=ff8cbf8212b71d918e37076d3452dcd0858f
c177def01fbf3565d8d8d19a7cb9
HTML response/Notification fields reference:
| Parameter | Description |
|---|---|
transactionid | payabl. internal transaction id. Please use this transaction id when referring to the transaction in communications with the payabl. team |
type | Transaction type |
errorcode | Transaction error code (0 for success) |
errormessage | Brief explanation of transaction decline reason (empty on success) |
orderid | Optional transaction identifier given by the merchant |
security | Signature to verify the authenticity of the notification. You can find more information here |
timestamp | Notification timestamp |
3dProtocolVersion | 3DS protocol version (will be 2.2.0 in most cases until further notice) |
3dauthentication_status | 3DS authentication status (possible values: Y, A, N, U, R) |
3dauthentication_flow | 3DS authentication flow (e.g. frictionless_flow) |
3dcardholderInformation | Only added on declined transactions to provide additional explanations to the customer. Present if bank sends it. |
You may find a full list of decline reasons in the annex.
As mentioned above, for non-3DS transactions there will be only server response.
Server response example: (for non-3DS)
transactionid=105226636&transid=105226636&status=0&errormessage=&errmsg=&amount=19.99&price=19.99¤cy=EUR&
orderid=Payabl-Test&user_id=466838
Server Response fields reference: (for non-3DS):
| Parameter | Description |
|---|---|
transactionid | payabl. internal transaction id. Please use this transaction id when referring to the transaction in communications with the payabl. team |
transid | The same as transactionid |
status | Transaction error code |
errormessage | Brief explanation of transaction decline reason (empty on success) |
errmsg | The same as errormessage |
amount | Transaction amount |
price | The same as amount |
currency | Transaction currency |
orderid | Optional transaction identifier given by the merchant |
user_id | Payment system user identifier |
Additional response and Callback parameters
Additional parameters maybe added to payabl. responses and notifications. Please contact Technical support to update your response settings.
The parameters below will provide more data on transaction details. They can be added to both responses and notifications:
| Parameter | Description |
|---|---|
bin | Customer bank BIN |
bin_country | Customer BIN country |
payment_method | payabl. payment method ID |
ccn_four | Last 4 digits of customer credit card number |
card_type | Customer card brand - also possible to include specific card type and credit/debit (example VISA INFINITE DEBIT) |
cardholder | Cardholder name |
expiry_month | Card expiry month |
expiry_year | Card expiry month |
amount | Transaction amount |
currency | Transaction currency |
Callback with additional parameters example:
orderid=Payabl-Test&bin_country=DEU&bin=414901&3dProtocolVersion=2.2.0&errorcode=0&3dauthentication_status=Y&3dauthentication_flow=challenge_flow&
ccn_four=0147&transactionid=105226638&payment_method=1&type=capture&card_type=VISA&cardholder=JOHN+DOE&errormessage=×tamp=1686140177&
security=ab680be69c2dd763285654ed6dcc0a0894b0210619f3e76f6a8895a953ab3bed
Response with additional parameters example: (for non-3DS)
transactionid=105095226&transid=105095226&status=0&errormessage=&errmsg=&amount=19.99&price=19.99¤cy=EUR&orderid=Payabl-Test&
bin=401200&payment_method=1&ccn_four=8889&card_type=VISA&cardholder=JOHN%20DOE&expiry_month=12&expiry_year=2026&amount=19.99&
currency=EUR&bin_country=RUS&user_id=466838
Our Technical Support team is there to help you:
Email: [email protected]
Available Monday – Friday between 09:00 and 17:00 CET/CEST
Updated 4 months ago