Introduction
Authentication
API requests authentication is made via HTTP Basic Auth. You have to send your API key as the HTTP password, and the user field should be left empty. We provide each merchant with the list of API permissions for their account. In the documentation, you can see the permission necessary for a specific request next to a key icon. As in:curl \ --user :mer_intg_FR2SUXtrnXgOL2KOHzcMQ9U96lJ3Wxjbr3nuvWD1UDNmyxLh \ https://api.straal.com/v1/cards
Responses
The result of your request is indicated by an HTTP status code. Basically all 2xx codes indicate success, and all 4xx codes indicate failure.HTTP status codes
200 | Request was validated and performed with success / Transaction succeeded |
400 | Usually indicates bad/malformed request data |
402 | Related to payments - indicates failure |
409 | Indicates conflict - e.g. when you're trying to make multiple transactions on one card at the same time |
Error responses
Each response with code 4xx has at least the errors field set, similar as below:{ "errors": [ {"code": 10111, "message": "Invalid card number"}, {"code": 10211, "message": "Invalid customer email"} ] }
Error responses related to payments
When API request fails due to payment errors, we return a response with HTTP status 402. In the errors list you will find a general error indicating payment failure, e.g.:{ "errors": [ {"code": 60001, "message": "Authorization failed"} ] }
Below are the most common decline reasons:
1001 | Declined by issuing bank Transaction declined by card issuer. Advise the cardholder to contact their bank and check card settings. |
1002 | Insufficient funds Transaction declined by card issuer - insufficient funds or limit exceeded. Please, ask the cardholder to contact their bank and check card settings. |
1003 | Expired card |
1004 | Internal error An error has occured on the side of the Straal. Please, contact Straal for more information and support. |
1005 | Invalid amount Transaction declined by card issuer - insufficient funds or limit exceeded. Please, ask the cardholder to contact their bank and check card settings. |
1006 | Invalid card data Transaction declined by card issuer - invalid card details. |
1007 | Restricted cardTransaction declined by card issuer. Please, ask the cardholder to contact their bank and check card settings. |
1008 | Invalid transaction Transaction declined by card issuer. Please, ask the cardholder to contact their bank and check card settings. |
1009 | Withdrawal limit exceeded Transaction declined by card issuer. Please, ask the cardholder to contact their bank and check card settings. |
1010 | Card not supported Transaction declined by acquirer - card type not supported. |
1011 | Transaction not permitted to cardholder Transaction declined by card issuer. Please, ask the cardholder to contact their bank and check card settings. |
1012 | Merchant account error Your merchant account is misconfigured. Please, contact Straal. |
1013 | Security violation Transaction declined by card issuer. Please, ask the cardholder to contact their bank and check card settings. |
1014 | Gateway frequency limit exceeded Acquirer activity limit exceeded. Please, contact Straal. |
1015 | Acquirer error An error has occured on the side of the acquiring bank. Please, contact Straal. |
1016 | Antifraud decline Transaction declined by Straal's antifraud system. |
1017 | Risk blocked in external payment system Transaction declined by Acquirer's antifraud system. |
1018 | Authentication 3DS failed Client not successfully authorized during 3DS process. |
1019 | SCA Required Additional customer authentication required. |
1101 | Possible fraud Transaction declined by card issuer. WARNING! The card has been designated as lost or stolen. DO NOT MAKE ANY FURTHER CHARGING ATTEMPTS - THOSE MIGHT BE CONSIDERED AS FRAUDULENT. |
2000 | Transaction declined General transaction decline. Please contact support for more information. |
Expanding objects
There are various relations between resources existing within Straal API. When retrieving an object using our API, you don't always need all associated objects. For performance and better readability reasons, our API implements the expand parameter, which can be used to retrieve few or all associated objects within one request. To expand multiple objects send a list delimited by ,.Example request for getting dummy_object
{ "id": "g0jk87sc", "is_dummy": true, "foo": { "id": "j5k3jdkwpmz", "bar": { "id": "j48k502kv" } } }
{ "id": "g0jk87sc", "is_dummy": true, "foo": { "id": "j5k3jdkwpmz", "is_foo_attribute": true, "number": 100, "bar": { "id": "j48k502kv", "is_bar_attribute": true, "string": "mlk-q" } } }
API changes
We will not make any breaking changes in the API. However, please note that adding new objects or attributes to existing objects is not considered a breaking change.Testing resources
You can use the following test credit card numbers and IBANs in your integration environment. Any expiration date in the future will be valid. Any CVV code will be valid. Cardholder name has to be at least 3 characters long to be valid.
3DSecure V2 Scenarios - with threeds_v2 params
Google Pay cards are taken from Test card suite
Apple Pay cards are taken from Test card suite
4532496353677072 | VISA - Card Not Enrolled - Error |
4556997398420643 | VISA - Network Error - Error |
4929111260419572 | VISA - Frictionless - Success |
4556786751817853 | VISA - Frictionless - Failure |
4716436222435110 | VISA - Challenge - Success |
4539365457901717 | VISA - Challenge - Failure |
4637198235600777 | VISA - Fallback - Success |
4485735629519684 | VISA - Fallback - Failure |
4444444444444448 | VISA - Frictionless with 3DS Method - Success |
4716530227063560 | VISA - Frictionless with 3DS Method - Success |
4539073978065588 | VISA - Frictionless with 3DS Method - Failure |
4929912607956345 | VISA - Challenge with 3DS Method - Success |
4539876025578860 | VISA - Challenge with 3DS Method - Failure |
4929859585677619 | VISA - Fallback with 3DS Method - Success |
4539505500852488 | VISA - Fallback with 3DS Method - Failure |
5267621579383431 | MasterCard - Card Not Enrolled - Error |
5297582308509601 | MasterCard - Network Error - Error |
5476405082219267 | MasterCard - Frictionless - Success |
5526468184255647 | MasterCard - Frictionless - Failure |
5593877707082957 | MasterCard - Challenge - Success |
5515402631026288 | MasterCard - Challenge - Failure |
5498177754250805 | MasterCard - Fallback - Success |
5481087000166599 | MasterCard - Fallback - Failure |
5319964426348431 | MasterCard - Frictionless with 3DS Method - Success |
5238079599747448 | MasterCard - Frictionless with 3DS Method - Failure |
5113003559062879 | MasterCard - Challenge with 3DS Method - Success |
5327657876521164 | MasterCard - Challenge with 3DS Method - Failure |
5348712805985199 | MasterCard - Fallback with 3DS Method - Success |
5191129590856840 | MasterCard - Fallback with 3DS Method - Failure |
xxxxxxxxxxxx1111 | Visa - Google Pay - Frictionless with 3DS Method - Success |
xxxxxxxxxxxx4444 | Mastercard - Google Pay - Frictionless with 3DS Method - Failure |
xxxxxxxxxxxx2222 | Visa - Google Pay - Challenge with 3DS Method - Success |
xxxxxxxxxxxx0005 | Amex - Google Pay - Challenge with 3DS Method - Failure |
4051069302200121 | Visa - Apple Pay - Frictionless with 3DS Method - Success |
5204247750001471 | Mastercard - Apple Pay - Frictionless with 3DS Method - Failure |
4180620070230189 | Visa - Apple Pay - Challenge with 3DS Method - Success |
5204245250001488 | Amex - Apple Pay - Challenge with 3DS Method - Failure |
3DSecure V1 Scenarios
4532496353677072 | VISA - Card Not Enrolled - Error |
4556997398420643 | VISA - Network Error - Error |
4444444444444448 | VISA - Successful 3DSecure authentication - Success |
4485282121221816 | VISA - Unsuccessful 3DSecure authentication - Failure | 4716292201436623 | VISA - 3D-Secure authentication completed, authorization failed - Failure |
4485819621877561 | VISA - network error 3D-Secure authentication failed to complete after redirect - Error |
5267621579383431 | MasterCard - Card Not Enrolled - Error |
5297582308509601 | MasterCard - Network Error - Error |
5306605065027191 | MasterCard - Successful 3DSecure authentication - Success |
5437554227710785 | MasterCard - Unsuccessful 3DSecure authentication - Failure |
5112630232543924 | MasterCard - 3D-Secure authentication completed, authorization failed - Failure |
5590867286010498 | MasterCard - network error 3D-Secure authentication failed to complete after redirect - Error |
Scenarios without 3DSecure
4444444444444448 | VISA - authorization result dependent on amount |
5555444433331111 | MasterCard - authorization result dependent on amount |
378282246310005 | American Express - authorization result dependent on amount |
4462030000000000 | VISA - subscriptions created with this card will be billed just once, moments after creation. Use it to test subscription notifications webhook. For the rest of test cards, subscriptions will be billed according to their plan. - Success |
4716436222435110 | VISA - Strong Customer Authentication card will return SCA required error - 3DS V2 is required |
5593877707082957 | MasterCard - Strong Customer Authentication card will return SCA required error - 3DS V2 is required |
Controlling test operation results with amount
You can use specific operation amounts to cause certain results. Examples:
- Amounts 4051 and 4005, when used with card numbers listed above, will result in a failed credit card authorization. Any other amount will be processed successfully.
- Amount 4055 will cause a credit request to fail. Any other amount will be processed successfully.
Testing SDP Payments on integration account
On the integration account redirect_url mentioned in SDP process overview, will redirect to the sandbox version of the app that allows selection of banks. It offers sandbox versions of real bank interfaces as well as demo banks.
Sample scenarios
Currency: PLN Result: Success
1 | Chose country Poland |
2 | Chose bank mBank |
3 | Confirm the payment with Accept button |
4 | On the sandbox bank page, chose AUTHORIZE option |
5 | Payment initiated successfully |
Currency: PLN Result: Failure
1 | Chose country Poland |
2 | Chose bank mBank |
3 | Confirm the payment with Accept button |
4 | On the sandbox bank page chose CANCEL option |
5 | Payment failure |
Currency: EUR GBP Result: Success
1 | Chose country United Kingdom |
2 | Chose bank Mock Redirect Bank |
3 | Confirm the payment with Accept button |
4 | Payment initiated successfully |
Currency: EUR GBP Result: Failure
1 | Chose country Hungary |
2 | Chose bank UniCredit Bank Hungary |
3 | Fill IBAN with test value (e.g. HU93116000060000000012345676) |
4 | Confirm the payment with Accept button |
5 | On Required credentials page chose Decline option |
6 | Payment failure |
Warning! Sandbox app and demo banks are maintained by third parties over whom Straal has no control
Changelog
2020-07-24
- Added external_reference attribute and description to customers.
2024-07-18
- Added Straal Direct Payment status change notification
- Removed Straal Direct Payment failed and Straal Direct Payment initiated notifications
- Updated straal-direct-payments resource
2024-03-XX
- Added Create a 3DS transaction with internal MPI engine
- Added Create a 3DS transaction with internal MPI engine using CryptKey
- Added threeds_redirection notification
2023-11-24
- Added APM payments related notifications
- Added APM payments section
- Added apm type to get the list of payment methods
- Added optional language parameter to pay-by-link payment object attributes and to initialize pay-by-link payments sample request
- Deprecated initialize a pay-by-link payment
2023-09-11
- Added sample checkout_attempt_finished notification for Google Pay and Apple Pay
2023-09-09
- Added sample request_finished notification for Google Pay and Apple Pay
2023-09-06
- Added Create a transaction with the Apple Pay 3D secure
- Added Create a 3DS transaction with the Apple Pay using CryptKey
- Added payment sample response in Get checkout object when using Apple Pay
- Added payment_mean_type parameter to Create a transaction for existing card with 3D secure
- Added payment_mean_type parameter to Create a transaction for existing card
- Updated Payment Means section with Apple Pay examples
2023-07-24
- Added Apple Pay card numbers to Testing resources
2023-07-12
- Added Create a transaction with the Google Pay 3D secure
- Added Create a 3DS transaction with the Google Pay using CryptKey
- Added Payment Means section
- Added payment sample response for Get checkout object when using Google Pay
- Updated payment sample response in Get checkout object when using Card
2023-06-27
- Added Google Pay card numbers to Testing resources
2023-02-23
- Added description of card tokenization and external MPI params with subscription flow
- Added transactions entry to subscription creation response
2021-12-23
- Removed all resources connected with Bank Accounts (SEPA Direct Debit transactions)
2021-09-01
- Added description of passing merchant risk params and billing address in server-to-server integration with CryptKey.
2021-05-17
- Added description of card billing address data.
- Added description of transaction merchant risk parameters.
2021-03-29
- Added description of Create a transaction with 3D secure
- Explained how to pre-authorize transactions.
- Added pre_auth to transaction object attributes
2020-12-17
- Added new card numbers to Testing resources
2020-12-01
- Added description of the new 3DS payments API flow using CryptKeys or server-to-server integration
- Deprecated the previous overview of a (two step) 3D secure transaction.
2020-11-06
- Added new card numbers to Testing resources
2020-10-19
- Added type parameter to transaction endpoints
- Deprecated initiated_by parameter in transaction endpoints
2020-09-14
- Updated Get a transaction and Get a list of transactions with optional authentication_3ds section
2020-08-25
- Removed backup routing create variant from transactions.
- attempts from transactions are now deprecated.
- Added with_3ds_params attribute and description to transactions.
2020-06-29
- Added documentation for credits
2020-06-16
- Added mpi_params to transactions attributes. Sample request moved under separate section Create a transaction with external MPI parameters
2020-05-05
- Added optional mpi_params structure to Create a transaction with a card request to enable 3D-Secure payments when the 3DS authentication was provided by an external MPI service.
2020-04-23
- Added external_reference attribute and description to transactions.
2020-04-20
- Added payer_iban and payer_name fields to straal_direct_payment_failed (empty values) and straal_direct_payment_initiated (actual data) notifications.
2020-03-16
- Added optional customer_name and iban arguments to Straal Direct Payment requests.
2020-03-11
- Added Mark card disabled endpoint to Cards section.
2019-11-21
- Added Things to keep in mind section to Straal Direct Payment description.
2019-11-08
- Added transaction to Straal Direct Payment creation and id to Straal Direct Payment notification.
2019-10-22
- Added draft section about Straal Direct Payments.
2019-09-16
- Added section on 3D-Secure payment process overview.
2019-07-16
- Added order_reference attribute description in transactions.
2019-07-01
- Deprecated endpoints:
2019-05-24
- Added order_reference attribute to transactions.
2019-05-22
- Added information about 3D-Secure authentication process.
2019-04-04
- Added a new checkout_attempt_finished notification to the Checkout Page section.
2019-02-18
- Added backup routing create variant to transactions.
- Added attempts to transactions.
2018-11-06
- Added method to transactions.
2018-10-10
- Added Voids section.
- Added voided and voids attributes to transactions.
2018-09-17
- Added Acquirer error to list of possible decline reasons.
- Updated description of Internal error since it no longer corresponds to acquirer errors.
2018-09-04
- Added Captures section.
- Added capture to transactions.
2018-08-31
- Added required initiated_by to Create a transaction and Create a transaction for a bank account sections.
2018-08-22
- Added state and state_flags to cards.
2018-04-24
- Added description of HTTP status 409 to HTTP response codes.
- Added start_date optional attribute to be set on subscriptions.
2018-04-19
- Added verification_transaction object to cards.
2018-04-04
- Extended response for Create a subscription with a card for a given customer and Create a subscription with a card and a customer endpoints:
- return any transaction objects created during subscription creation attempt
- return card and customer objects, if created, even on failed subscription creation attempt
2018-03-27
- Added Card transaction chargeback notification section.
2018-02-16
- Added Create a subscription with a card for a given customer section.
2018-02-15
- Extended cancellation_source values list.
2018-01-16
- Added cancellation_source object to subscriptions.
2018-01-12
- Added Create a transaction with a card using CryptKey section.
- Added Create a card using CryptKey section.
- Changed CryptKeys usage section.
2017-09-13
- Added decline_reason attribute to transactions.
2017-07-27
- Added reference attribute to transactions.
Resources
Transactions
A transaction object represents a real transaction performed on a credit card or a bank account. If the transaction succeeded, the authorized attribute is set to true.Transaction object attributes
- oneshot - disables the card and forbids any future use after the first transaction (e.g. customer did not agree to have his card data saved for future use)
- oneclick - permits future use of the card in subsequent transactions initiated by the customer (e.g. one-click checkout)
- recurring - permits future use of the card in subsequent transactions initiated by the merchant (subscriptions or other periodic payments)
This field is required when you create a transaction for an already existing card or bank account. Possible values are merchant and customer. A transaction is initiated by a customer when she/he takes an action to make a payment - clicks on a Pay button etc. A transaction is initiated by a merchant when it is a recurring payment made by a merchant's backend.
Sample decline_reason:
{ "code": 1001, "description": "Declined by issuing bank" }
Pre-authorization
To pre-authorize a transaction, set capture to false and pre_auth param to true. Pre-authorized transactions can be voided or captured.Create a transaction
This method allows you to perform a transaction on a previously created card object.type can take values oneclick or recurring.
Use this method for Google Pay and Apple Pay.
{ "amount": 999, "currency": "usd", "reference": "b138bc50148440ee", "type": "oneclick", "payment_mean_type": "card" }
Sample response:
{ "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "usd", "method": "card", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "qkymdfy2jbui1", "created_at": 1470239156, "amount": 999 } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": "44177a21403427eb96664a6d7e5d5d48", "order_reference": null, "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "decline_reason": null, "extra_data": {} }
{ "amount": 999, "currency": "usd", "reference": "b138bc50148440ee", "type": "oneclick", "payment_mean_type": "google_pay" }
{ "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "usd", "method": "google_pay", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "qkymdfy2jbui1", "created_at": 1470239156, "amount": 999 } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": "44177a21403427eb96664a6d7e5d5d48", "order_reference": null, "google_pay": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "decline_reason": null, "extra_data": {} }
{ "amount": 999, "currency": "usd", "reference": "b138bc50148440ee", "type": "oneclick", "payment_mean_type": "apple_pay" }
{ "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "usd", "method": "apple_pay", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "qkymdfy2jbui1", "created_at": 1470239156, "amount": 999 } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": "44177a21403427eb96664a6d7e5d5d48", "order_reference": null, "apple_pay": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "decline_reason": null, "extra_data": {} }
Create a transaction for existing card with 3D secure
This method allows you to perform a transaction with 3DS on a previously created card object. We recommend using this SCA-enabled flow if you need to handle customer-initiated payments (e.g. "one-click" transactions). Please contact our support to check that this method is recommended in your business case.If the customer's card is enrolled in 3DS, this payment is asynchronous. Redirect your customer to the redirect_url returned under authentication_3ds object and wait for the request_finished notification to receive the final status of the payment.
To learn more about the 3D Secure payment process, refer to the description of a full card data payment with 3DS.
Use transaction for previously created card method instead without providing authentication_3ds object for Google Pay and Apple Pay. Even if authentication_3ds object is sent for Google Pay and Apple Pay transaction will proceed without 3ds.
type can only take value oneclick.
Sample request for a $9.99 transaction
{ "amount": 999, "currency": "usd", "reference": "b138bc50148440ee", "type": "oneclick", "payment_mean_type": "card", "authentication_3ds": { "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "threeds_v2": { "browser": { "accept_header": "*/*", "color_depth": 24, "java_enabled": false, "language": "pl-PL", "screen_height": 1080, "screen_width": 1920, "timezone": -60, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "ip": "213.120.141.140" } } } }
Sample response:
{ "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "usd", "method": "card", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "qkymdfy2jbui1", "created_at": 1470239156, "amount": 999 } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": "44177a21403427eb96664a6d7e5d5d48", "order_reference": null, "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "decline_reason": null, "extra_data": {}, "authentication_3ds": { "id": "a7lr1cpt2fzqk", "created_at": 1606135550, "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "enrollment_status": "Y", "errors": [], "status": "pending", "protocol_version": "1.0", "eci": null, "threeds_flow": null, "threeds_v2": { "browser": { "accept_header": "*/*", "color_depth": 24, "java_enabled": false, "language": "pl-PL", "screen_height": 1080, "screen_width": 1920, "timezone": -60, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "ip": "213.120.141.140" } }, "redirect_url": "https://checkout.straal.com/authentications_3ds/some_token" } }
Create a transaction with external MPI parameters
It's also possible to provide an optional 3D-Secure MPI data structure if the 3DS authentication has been performed by external MPI system. Optional mpi_params could be included in any of the following card transaction requests:Create a transaction,
Create a transaction with a card,
mpi_params object for 3DS protocol version 1.
{ "amount": 999, "currency": "usd", "reference": "b138bc50148440yy", "type": "oneclick", "mpi_params": { "protocol_version": "1.0", "xid": "ODUzNTYzOTcwODU5NzY3Qw==", "cavv": "jJ81HADVRtXfCBATEp01CJUAAAA=", "eci": "05" } }
{ "id": "p4sacj0gl5r7c", "card": { "id": "wjyjp7c87wp7c", "customer": { "id": "j9ubc9jou7c7a", "last_transaction": { "id": "p4sacj0gl5r7c" } } }, "captures": [ { "id": "jyjcbrrtphc75", "created_at": 1592302456, "amount": 999, "status": "succeeded", "extra_data": {} } ], "refunds": [], "voids": [], "attempts": [], "with_3ds_params": true, "mpi_params": { "cavv": "Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=", "ds_transaction_id": "231123123312", "eci": "05", "xid": "VEw4TkFrakFYMmEreXdoZE5xZUU=", "protocol_version": "2.1.0" }, "created_at": 1592302452, "amount": 999, "currency": "usd", "authorized": true, "pre_auth": false, "captured": true, "refunded": false, "extra_data": {}, "straal_custom_data": {}, "chargeback": null, "reference": "b138bc50148440yy", "external_reference": null, "order_reference": null, "decline_reason": null, "voided": false, "method": "card" }
Create a card transaction with 3D Secure
This one step flow is a simpler alternative to the process described in our previous (deprecated) overview of a two step 3D secure transaction.
If the card is enrolled in 3DS program, this API request will be asynchronous: on the authentication_3ds object in the response payload you will receive a URL to redirect your customer to. The resulting transaction will not yet be authorized.
During the transaction, the customer will be redirected to a page provided by the acquirer (redirect_url) to complete 3D-Secure process. After the customer completes interaction with the page, he will be redirected back to merchant's page.
After finishing the authentication process, your customer's card will be charged and they will be redirected to the success or failure URL provided in your request.
You will receive the final transaction result in a request_finished notification on your backend (see below). To receive notifications you need to set up the notification endpoint URL for your account in the Kompas panel.
If you are not PCI certified to process payment data or you haven't submitted PCI Self-Assessment Questionnaire type "D" (for more details please refer to Straal docs > PCI Compliance), use the CryptKey flow as described here.
Sample request for a $9.99 transaction with 3DS
{ "amount": 999, "currency": "usd", "reference": "b138bc50148440ee", "order_reference": null, "type": "oneclick", "capture": true, "card": { "name": "John Smith", "number": "4444444444444448", "cvv": "123", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "91.17.133.219" }, "authentication_3ds": { "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "threeds_v2": { "browser": { "accept_header": "*/*", "color_depth": 24, "java_enabled": false, "language": "pl-PL", "screen_height": 1080, "screen_width": 1920, "timezone": -60, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "ip": "213.120.141.140" } } } }
You can set capture value to false in order to make a preauthorization with 3D Secure. Then you can void the transaction or do the capture.
Sample success (pending) response, the authentication_3ds object contents may be extended.
{ "id": "fkc1arotl6kq3", "attempts": [], "with_3ds_params": false, "created_at": 1606135550, "amount": 999, "currency": "usd", "method": "card", "authorized": false, "captured": false, "captures": [], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc5014844a44", "external_reference": "298756cf16a585af9a9e5e09fb818432", "order_reference": null, "card": { "id": "0mcka1vh1fkqu", "customer": { "id": "bgl1cfyz35sj2", "last_transaction": { "id": "fkc1arotl6kq3" } }, "created_at": 1606135550, "brand": "visa", "name": "John Smith", "num_bin": "444444", "num_last_4": "4448", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "91.17.133.219", "extra_data": {}, "straal_custom_data": {}, "state": "active", "state_flags": [] }, "authentication_3ds": { "id": "a7lr1cpt2fzqk", "created_at": 1606135550, "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "enrollment_status": "Y", "errors": [], "status": "pending", "protocol_version": "1.0", "eci": null, "threeds_flow": null, "threeds_v2": { "browser": { "accept_header": "*/*", "color_depth": 24, "java_enabled": false, "language": "pl-PL", "screen_height": 1080, "screen_width": 1920, "timezone": -60, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "ip": "213.120.141.140" } }, "redirect_url": "https://checkout.straal.com/authentications_3ds/some_token" }, "decline_reason": null, "extra_data": {}, "straal_custom_data": {} }
{ "id": "fkc1arotl6kq3", "attempts": [], "with_3ds_params": false, "created_at": 1606135550, "amount": 999, "currency": "usd", "method": "card", "authorized": false, "captured": false, "captures": [], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc5014844a44", "external_reference": "298756cf16a585af9a9e5e09fb818432", "order_reference": null, "card": { "id": "0mcka1vh1fkqu", "customer": { "id": "bgl1cfyz35sj2", "last_transaction": { "id": "fkc1arotl6kq3" } }, "created_at": 1606135550, "brand": "visa", "name": "John Smith", "num_bin": "453249", "num_last_4": "7072", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "91.17.133.219", "extra_data": {}, "straal_custom_data": {}, "state": "active", "state_flags": [] }, "authentication_3ds": { "id": "gxb1acbkr8rqa", "created_at": 1606136918, "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "enrollment_status": "N", "errors": [ { "code": 17015, "message": "3DS authentication failed" } ], "status": "failed", "protocol_version": "1.0", "threeds_v2": { "browser": { "accept_header": "*/*", "color_depth": 24, "java_enabled": false, "language": "pl-PL", "screen_height": 1080, "screen_width": 1920, "timezone": -60, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "ip": "213.120.141.140" } } }, "errors": [ { "code": 60001, "message": "Authorization failed" }, { "code": 17015, "message": "3DS authentication failed" } ], "decline_reason": { "code": 1018, "description": "3DS Authentication failed" }, "extra_data": {}, "straal_custom_data": {} }
Wait for the request_finished notification on your backend. This notification will contain the final state of this payment. You don't need to finalize the transaction as you would using the (deprecated) two step 3D secure transaction.
Please note that we send the request finished notification for all transaction-related requests (which means for majority of POST requests to our API). Filter out the relevant notifications by checking the permission field.
The request_finished notification for the 3DS transaction will have permission field set to v1.transactions.create_with_card and the response object will be the final state of the transaction object that you received in the API response before redirecting the customer.
A successful 3DS transaction will be authorized and the authentication_3ds will have status "succeeded". If you requested a captured transaction, which is the default, it should also be captured.
{ "event": "request_finished", "data": { "path": "/v1/customers/mzivhql5yi9rf/transactions", "permission": "v1.transactions.create_with_card", "auth_method": "apikey", "cryptkey": {}, "request_id": "0e04ead77926441c9369f1932ddd13c8", "response": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": true, "created_at": 1470238921, "amount": 999, "currency": "usd", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "qkymdfy2jbui1", "created_at": 1470239156, "amount": 999 } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "authentication_3ds": { "id": "688xc7ogyc5ja", "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "status": "succeeded", "created_at": 1472491822, "enrollment_status": "Y", "errors": [], "threeds_v2": { "browser": { "accept_header": "*/*", "color_depth": 24, "java_enabled": false, "language": "pl-PL", "screen_height": 1080, "screen_width": 1920, "timezone": -60, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "ip": "213.120.141.140" } } }, "decline_reason": null, "extra_data": {} } } }
An example of the request_finished notification for a failed 3DS transaction (in this example, the 3DS authentication has succeeded but there were insufficient funds on the customer's account):
{ "event": "request_finished", "data": { "path": "/v1/customers/mzivhql5yi9rf/transactions", "permission": "v1.transactions.create_with_card", "auth_method": "apikey", "cryptkey": {}, "request_id": "0e04ead77926441c9369f1932ddd13c8", "response": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": true, "created_at": 1470238921, "amount": 999, "currency": "usd", "authorized": false, "captured": false, "captures": [], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "authentication_3ds": { "id": "688xc7ogyc5ja", "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "status": "succeeded", "created_at": 1472491822, "enrollment_status": "Y", "errors": [], "threeds_v2": { "browser": { "accept_header": "*/*", "color_depth": 24, "java_enabled": false, "language": "pl-PL", "screen_height": 1080, "screen_width": 1920, "timezone": -60, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "ip": "213.120.141.140" } } }, "decline_reason": { "code": 1002, "description": "Insufficient funds" }, "extra_data": {} } } }
Create a card transaction with 3D Secure (Internal MPI Engine)
If the card is enrolled in 3DS program, this API request will be asynchronous: on the authentication_3ds object in the response payload you will receive a URL to redirect your customer to. The resulting transaction will not yet be authorized.
At the beginning of transaction the customer will be redirected to a page responsible for browser profiling (profiling_url) to colect data about customer's browser.
In second step customer will be moved to his bank's website to complete 3DS process.
After successful 3DS customer will be redirected to the straal-checkout loading page. In the background we'll perform a transaction with received mpi-params.
After finishing the authentication process, your customer's card will be charged and they will be redirected to the success or failure URL provided in your request.
You will receive the final transaction result in a request_finished notification on your backend (see below). To receive notifications you need to set up the notification endpoint URL for your account in the Kompas panel.
If you are not PCI certified to process payment data or you haven't submitted PCI Self-Assessment Questionnaire type "D" (for more details please refer to Straal docs > PCI Compliance), use the CryptKey flow as described here.
Sample request for a $9.99 transaction with 3DS
{ "amount": 999, "currency": "usd", "reference": "b138bc50148440ee", "order_reference": null, "type": "oneshot", "capture": true, "card": { "name": "John Smith", "number": "4444444444444448", "cvv": "123", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "91.17.133.219" }, "authentication_3ds": { "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail" } }
You can set capture value to false in order to make a preauthorization with 3D Secure. Then you can void the transaction or do the capture.
Sample pending response, the authentication_3ds object contents may be extended.
{ "id": "fkc1arotl6kq3", "attempts": [], "with_3ds_params": false, "created_at": 1606135550, "amount": 999, "currency": "usd", "method": "card", "authorized": false, "captured": false, "captures": [], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc5014844a44", "external_reference": "298756cf16a585af9a9e5e09fb818432", "order_reference": null, "card": { "id": "0mcka1vh1fkqu", "customer": { "id": "bgl1cfyz35sj2", "last_transaction": { "id": "fkc1arotl6kq3" } } }, "authentication_3ds": { "id": "a7lr1cpt2fzqk", "created_at": 1606135550, "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "enrollment_status": "Y", "errors": [], "status": "pending", "protocol_version": "2.2.0", "eci": null, "threeds_flow": null, "threeds_v2": null, "redirect_url": "https://checkout.straal.com/authentications_3ds/some_token" }, "decline_reason": null, "extra_data": {}, "straal_custom_data": {} }
{ "id": "fkc1arotl6kq3", "attempts": [], "with_3ds_params": false, "created_at": 1606135550, "amount": 999, "currency": "usd", "method": "card", "authorized": false, "captured": false, "captures": [], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc5014844a44", "external_reference": "298756cf16a585af9a9e5e09fb818432", "order_reference": null, "card": { "id": "0mcka1vh1fkqu", "customer": { "id": "bgl1cfyz35sj2", "last_transaction": { "id": "fkc1arotl6kq3" } } }, "authentication_3ds": { "id": "a7lr1cpt2fzqk", "created_at": 1606135550, "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "enrollment_status": "Y", "errors": [ { "code": 17013, "message": "Initialize 3DS failed" } ], "status": "failed", "protocol_version": "2.2.0", "eci": null, "threeds_flow": null, "threeds_v2": null, "redirect_url": "https://checkout.straal.com/authentications_3ds/some_token" }, "decline_reason": null, "extra_data": {}, "straal_custom_data": {} }
Wait for the request_finished notification on your backend. This notification will contain the final state of this payment.
Please note that we send the request finished notification for all transaction-related requests (which means for majority of POST requests to our API). Filter out the relevant notifications by checking the permission field.
The request_finished notification for the 3DS transaction will have permission field set to v1.transactions.create_with_card_3ds and the response object will be the final state of the transaction object that you received in the API response before redirecting the customer.
A successful 3DS transaction will be authorized and the authentication_3ds will have status "succeeded". If you requested a captured transaction, which is the default, it should also be captured.
{ "event": "request_finished", "data": { "path": "/v1/customers/mzivhql5yi9rf/transactions_3ds", "permission": "v1.transactions.create_with_card_3ds", "auth_method": "apikey", "cryptkey": {}, "request_id": "0e04ead77926441c9369f1932ddd13c8", "response": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": true, "created_at": 1470238921, "amount": 999, "currency": "usd", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "qkymdfy2jbui1", "created_at": 1470239156, "amount": 999 } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "authentication_3ds": { "id": "688xc7ogyc5ja", "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "status": "succeeded", "created_at": 1472491822, "enrollment_status": "Y", "errors": [] }, "decline_reason": null, "extra_data": {} } } }
An example of the request_finished notification for a failed 3DS transaction (in this example, the 3DS authentication has succeeded but there were insufficient funds on the customer's account):
{ "event": "request_finished", "data": { "path": "/v1/customers/mzivhql5yi9rf/transactions_3ds", "permission": "v1.transactions.create_with_card_3ds", "auth_method": "apikey", "cryptkey": {}, "request_id": "0e04ead77926441c9369f1932ddd13c8", "response": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": true, "created_at": 1470238921, "amount": 999, "currency": "usd", "authorized": false, "captured": false, "captures": [], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "authentication_3ds": { "id": "688xc7ogyc5ja", "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "status": "succeeded", "created_at": 1472491822, "enrollment_status": "Y", "errors": [], "threeds_v2": { "browser": { "accept_header": "*/*", "color_depth": 24, "java_enabled": false, "language": "pl-PL", "screen_height": 1080, "screen_width": 1920, "timezone": -60, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "ip": "213.120.141.140" } } }, "decline_reason": { "code": 1002, "description": "Insufficient funds" }, "extra_data": {} } } }
Create a Google Pay transaction with 3D Secure
{ "amount": 999, "currency": "usd", "reference": "b138bc50148440ee", "order_reference": null, "type": "oneclick", "capture": true, "card": { "type": "google_pay", "origin_ipaddr": "91.17.133.219", "payment_data": { "apiVersion": 2, "apiVersionMinor": 0, "email": "[email protected]", "paymentMethodData": { "type": "CARD", "description": "Visaxxxx1234", "info": { "cardNetwork": "VISA", "cardDetails": "1234" }, "tokenizationData": { "type": "PAYMENT_GATEWAY", "token": "examplePaymentMethodToken" } } } }, "authentication_3ds": { "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "threeds_v2": { "browser": { "accept_header": "*/*", "color_depth": 24, "java_enabled": false, "language": "pl-PL", "screen_height": 1080, "screen_width": 1920, "timezone": -60, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "ip": "213.120.141.140" } } } }
Sample success (pending) response
{ "id": "78nfj31vw7tr0", "google_pay": { "id": "7z7jl7av0uprt", "customer": { "id": "0kj1yt1xb77r5", "last_transaction": { "id": "78nfj31vw7tr0" } }, "created_at": 1687426152, "type": "google_pay", "brand": "visa", "num_bin": null, "num_last_4": null, "expiry_month": null, "expiry_year": null, "origin_ipaddr": "91.17.133.219" }, "authentication_3ds": { "id": "79jzj8jv97tr0", "created_at": 1687426152, "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "enrollment_status": "Y", "errors": [], "status": "pending", "eci": null, "protocol_version": "2.1.0", "threeds_flow": null, "threeds_v2": { "browser": { "ip": "213.120.141.140", "language": "pl-PL", "timezone": -60, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "color_depth": 24, "java_enabled": false, "screen_width": 1920, "accept_header": "*/*", "screen_height": 1080, "javascript_enabled": true}}, "redirect_url": "https://checkout.straal.com/authentications_3ds/some_token"}, "captures": [ { "id": "75scjbyv07tr0", "status": "pending", "created_at": 1687426152, "amount": 999, "extra_data": {} } ], "refunds": [], "voids": [], "attempts": [], "created_at": 1687426152, "amount": 999, "currency": "usd", "authorized": false, "pre_auth": false, "captured": false, "refunded": false, "extra_data": {}, "straal_custom_data": {}, "chargeback": null, "reference": null, "external_reference": "298756cf16a585af9a9e5e09fb818f91", "order_reference": null, "decline_reason": null, "with_3ds_params": false, "voided": false, "method": "google_pay" }
{ "id": "to7jy7ff6hjrp", "google_pay": { "id": "7z7jl7av0uprt", "customer": { "id": "0kj1yt1xb77r5", "last_transaction": { "id": "to7jy7ff6hjrp" } }, "created_at": 1687427857, "type": "google_pay", "brand": "visa", "num_bin": null, "num_last_4": null, "expiry_month": null, "expiry_year": null, "origin_ipaddr": "91.17.133.219" }, "authentication_3ds": { "id": "6jzj7h8f7khrt", "created_at": 1687427857, "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "enrollment_status": "U", "errors": [ { "code": 17015, "message": "3DS authentication failed" } ], "status": "failed", "eci": null, "protocol_version": "2.1.0", "threeds_flow": null, "threeds_v2": { "browser": { "ip": "213.120.141.140", "language": "pl-PL", "timezone": -60, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "color_depth": 24, "java_enabled": false, "screen_width": 1920, "accept_header": "*/*", "screen_height": 1080, "javascript_enabled": true } }, "redirect_url": "http://www.example.merchant_url/fail"}, "captures": [ { "id": "tujhx7gf6hjr0", "status": "failed", "created_at": 1687427857, "amount": 999, "extra_data": {} } ], "refunds": [], "voids": [], "errors": [ { "code": 60001, "message": "Authorization failed" }, { "code": 17015, "message": "3DS authentication failed" } ], "attempts": [], "created_at": 1687427857, "amount": 999, "currency": "usd", "authorized": false, "pre_auth": false, "captured": false, "refunded": false, "extra_data": {}, "straal_custom_data": {}, "chargeback": null, "reference": null, "external_reference": "298756cf16a585af9a9e5e09fb818f91", "order_reference": null, "decline_reason": { "code": 1018, "description": "3DS Authentication failed" }, "with_3ds_params": false, "voided": false, "method": "google_pay" }
Create a Apple Pay transaction with 3D Secure
{ "amount": 999, "currency": "usd", "reference": "b138bc50148440ee", "order_reference": null, "type": "oneclick", "capture": true, "card": { "type": "apple_pay", "origin_ipaddr": "91.17.133.219", "payment_data": { "token": { "paymentData": { "data": "oSXLIUh9dmJK6D3nB1I3BKabO1hF3n+ScnQYw==", "signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDAAAAAAAA", "header": { "publicKeyHash": "Mjiu4PLiqVUKhKO5bX55JoNA1VMN2kIRIzPF8XV0cfc=", "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj==", "transactionId": "88e209d0c9ad440b4442857e562c796b3e759871" }, "version": "EC_v1" }, "paymentMethod": { "displayName": "MasterCard 1234", "network": "MasterCard", "type": "credit" }, "transactionIdentifier": "88E209D0C9AD440BC9C319FC7C24AB6E7" }, "billingContact": { "familyName": "", "givenName": "", "phoneticFamilyName": "", "phoneticGivenName": "" } } }, "authentication_3ds": { "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "threeds_v2": { "browser": { "accept_header": "*/*", "color_depth": 24, "java_enabled": false, "language": "pl-PL", "screen_height": 1080, "screen_width": 1920, "timezone": -60, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "ip": "213.120.141.140" } } } }
Sample success (pending) response:
{ "id": "78nfj31vw7tr0", "apple_pay": { "id": "7z7jl7av0uprt", "customer": { "id": "0kj1yt1xb77r5", "last_transaction": { "id": "78nfj31vw7tr0" } }, "created_at": 1687426152, "type": "apple_pay", "brand": "mastercard", "num_bin": null, "num_last_4": null, "expiry_month": null, "expiry_year": null, "origin_ipaddr": "91.17.133.219" }, "authentication_3ds": { "id": "79jzj8jv97tr0", "created_at": 1687426152, "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "enrollment_status": "Y", "errors": [], "status": "pending", "eci": null, "protocol_version": "2.1.0", "threeds_flow": null, "threeds_v2": { "browser": { "ip": "213.120.141.140", "language": "pl-PL", "timezone": -60, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "color_depth": 24, "java_enabled": false, "screen_width": 1920, "accept_header": "*/*", "screen_height": 1080, "javascript_enabled": true}}, "redirect_url": "https://checkout.straal.com/authentications_3ds/some_token"}, "captures": [ { "id": "75scjbyv07tr0", "status": "pending", "created_at": 1687426152, "amount": 999, "extra_data": {} } ], "refunds": [], "voids": [], "attempts": [], "created_at": 1687426152, "amount": 999, "currency": "usd", "authorized": false, "pre_auth": false, "captured": false, "refunded": false, "extra_data": {}, "straal_custom_data": {}, "chargeback": null, "reference": null, "external_reference": "298756cf16a585af9a9e5e09fb818f91", "order_reference": null, "decline_reason": null, "with_3ds_params": false, "voided": false, "method": "apple_pay" }
{ "id": "to7jy7ff6hjrp", "apple_pay": { "id": "7z7jl7av0uprt", "customer": { "id": "0kj1yt1xb77r5", "last_transaction": { "id": "to7jy7ff6hjrp" } }, "created_at": 1687427857, "type": "apple_pay", "brand": "mastercard", "num_bin": null, "num_last_4": null, "expiry_month": null, "expiry_year": null, "origin_ipaddr": "91.17.133.219" }, "authentication_3ds": { "id": "6jzj7h8f7khrt", "created_at": 1687427857, "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "enrollment_status": "U", "errors": [ { "code": 17015, "message": "3DS authentication failed" } ], "status": "failed", "eci": null, "protocol_version": "2.1.0", "threeds_flow": null, "threeds_v2": { "browser": { "ip": "213.120.141.140", "language": "pl-PL", "timezone": -60, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "color_depth": 24, "java_enabled": false, "screen_width": 1920, "accept_header": "*/*", "screen_height": 1080, "javascript_enabled": true } }, "redirect_url": "http://www.example.merchant_url/fail"}, "captures": [ { "id": "tujhx7gf6hjr0", "status": "failed", "created_at": 1687427857, "amount": 999, "extra_data": {} } ], "refunds": [], "voids": [], "errors": [ { "code": 60001, "message": "Authorization failed" }, { "code": 17015, "message": "3DS authentication failed" } ], "attempts": [], "created_at": 1687427857, "amount": 999, "currency": "usd", "authorized": false, "pre_auth": false, "captured": false, "refunded": false, "extra_data": {}, "straal_custom_data": {}, "chargeback": null, "reference": null, "external_reference": "298756cf16a585af9a9e5e09fb818f91", "order_reference": null, "decline_reason": { "code": 1018, "description": "3DS Authentication failed" }, "with_3ds_params": false, "voided": false, "method": "apple_pay" }
Create a 3DS transaction with a card using CryptKey
Learn below how to perform a card transaction with 3D Secure by sending sensitive data directly from a mobile application or website frontend code, so no card data hits your servers, which results in improved security and fewer PCI compliance requirements.By performing the steps below you will register a card and perform a $9.99 transaction on it, protected by 3D Secure protocol.
1. Create CryptKey with v1.transactions.create_with_card permission
It has to be done from your application backend, and the request has to be authorized by an APIKey with the correct permission. Transaction details have to be sent along with create CryptKey request. Similarly to server-to-server variant, you need to provide customer result URLs to your transaction data. Since this method is always executed within the customer context, you have to also include customer_id in the request payload. Sample request:
{ "permission": "v1.transactions.create_with_card", "customer_id": "auIj01kcj98lfq", "transaction": { "amount": 999, "currency": "usd", "capture": true, "type": "oneclick", "reference": "b138bc50148440ee", "extra_data": { "key": "value" }, "authentication_3ds": { "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "threeds_v2": { "browser": { "accept_header": "*/*", "color_depth": 24, "java_enabled": false, "language": "pl-PL", "screen_height": 1080, "screen_width": 1920, "timezone": -60, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "ip": "213.120.141.140" } } }, "merchant_risk_params": { "departure_date": "2021-01-13", "arrival_date": "2021-01-18" } } }
You can set capture value to false in order to make a preauthorization with 3D Secure. Then you can void the transaction or do the capture.
reference and extra_data are optional, authentication_3ds is required if you want to trigger 3DS authentication for customer.
Merchant risk params is optional, but can be required for some merchant types with particular acquirers.
Browser part of 3DS v2 parameters is optional in this request, but if not provided, Browser object should be included in encrypted payload as described in step 3.
2. Pass CryptKey into your frontend code
The preferred method to achieve this would be to send a request to your backend. But you could include the CryptKey value somewhere in your HTML code.
3. Encrypt the card data and send it directly to Straal API
A request containing card data should have the following format:
{ "name": "John Smith", "number": "4444444444444448", "cvv": "123", "expiry_month": 11, "expiry_year": 2021, "browser": { "color_depth": 24, "java_enabled": false, "language": "pl-PL", "screen_height": 1080, "screen_width": 1920, "timezone": -60 }, "billing_address": { "street_addr": "Plac Defilad 1", "postal_code": "00-901", "city": "Warszawa", "country": "Polska", "country_code": "PL" } }
Billing address is optional, but can be required for some merchant types with particular acquirers.
The response body will contain a request_id field which should be matched later on with the request_finished notification.
{ "request_id": "0e04ead77926441c9369f1932ddd13c8" }
4. Redirect your customer to the provided URL
If the request is successful (status code 200), you will receive a Location header along with the response. Redirect your customer to this URL for him to complete the 3D-Secure verification process.
If you are using Straal.js, it will automatically redirect your customer. After the 3D-Secure verification is finished, your customer will be redirected back to one of the specified URLs (success_url or failure_url) depending on the outcome of the 3D-Secure verification.
5. Wait for the request_finished notification on your backend (>>>you need to set up the notification endpoint URL for your account in the Kompas panel). This notification will contain the final state of this payment. You don't need to finalize the transaction as you would using the (deprecated) two step 3D secure transaction. Please note that we send the request finished notification for all transaction-related requests (which means for majority of POST requests to our API). Filter out the relevant notifications by checking the permission field, which in this flow is v1.transactions.create_with_card.
The request_finished notification for the 3DS transaction will have permission field set to v1.transactions.create_with_card and the response object will be the final state of the transaction object that was created in the encrypted request from the front-end. In the data you will also find request_id of the front-end request as well as cryptkey ID that was used.
The request_finished notification for the 3DS transaction will have the following format. A successful 3DS transaction will be authorized and the authentication_3ds will have status "succeeded". If you requested a captured transaction, which is the default, it should also be captured.
{ "event": "request_finished", "data": { "path": "/v1/customers/mzivhql5yi9rf/transactions", "permission": "v1.transactions.create_with_card", "auth_method": "cryptkey", "cryptkey": { "id": "70xfzmynzgkih" }, "request_id": "0e04ead77926441c9369f1932ddd13c8", "response": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": true, "created_at": 1470238921, "amount": 999, "currency": "usd", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "qkymdfy2jbui1", "created_at": 1470239156, "amount": 999 } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "authentication_3ds": { "id": "8dc41dh1drlqm", "status": "succeeded", "created_at": 1606128812, "failure_url": "http://www.example.merchant_url/fail", "success_url": "http://www.example.merchant_url/success", "threeds_params": null, "protocol_version": "1.0", "enrollment_status": "Y", "eci": "05", "threeds_flow": "frictionless", "errors": [], "threeds_v2": { "browser": { "accept_header": "*/*", "color_depth": 24, "java_enabled": false, "language": "pl-PL", "screen_height": 1080, "screen_width": 1920, "timezone": -60, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "ip": "213.120.141.140" } } }, "decline_reason": null, "extra_data": {} } } }
{ "event": "request_finished", "data": { "path": "/v1/customers/mzivhql5yi9rf/transactions", "permission": "v1.transactions.create_with_card", "auth_method": "cryptkey", "cryptkey": { "id": "70xfzmynzgkih" }, "request_id": "0e04ead77926441c9369f1932ddd13c8", "response": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": true, "created_at": 1470238921, "amount": 999, "currency": "usd", "authorized": false, "captured": false, "captures": [], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "authentication_3ds": { "id": "1q43cj6o3w8qv", "status": "succeeded", "created_at": 1606134039, "failure_url": "http://www.example.merchant_url/fail", "success_url": "http://www.example.merchant_url/success", "threeds_params": null, "protocol_version": "1.0", "enrollment_status": "Y", "errors": [], "threeds_v2": { "browser": { "accept_header": "*/*", "color_depth": 24, "java_enabled": false, "language": "pl-PL", "screen_height": 1080, "screen_width": 1920, "timezone": -60, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "ip": "213.120.141.140" } } }, "decline_reason": { "code": 1002, "description": "Insufficient funds" }, "extra_data": {} } } }
Create a 3DS transaction with a card using CryptKey (Internal MPI Engine)
Learn below how to perform a card transaction with 3D Secure by sending sensitive data directly from a mobile application or website frontend code, so no card data hits your servers, which results in improved security and fewer PCI compliance requirements.By performing the steps below you will register a card and perform a $9.99 transaction on it, protected by 3D Secure protocol using our internal MPI engine.
1. Create CryptKey with v1.transactions.create_with_card_3ds permission
It has to be done from your application backend, and the request has to be authorized by an APIKey with the correct permission. Transaction details have to be sent along with create CryptKey request. Similarly to server-to-server variant, you need to provide customer result URLs to your transaction data. Since this method is always executed within the customer context, you have to also include customer_id in the request payload. Sample request:
{ "permission": "v1.transactions.create_with_card_3ds", "customer_id": "auIj01kcj98lfq", "transaction": { "amount": 999, "currency": "usd", "capture": true, "type": "oneshot", "reference": "b138bc50148440ee", "extra_data": { "key": "value" }, "authentication_3ds": { "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail" }, "merchant_risk_params": { "departure_date": "2021-01-13", "arrival_date": "2021-01-18" } } }
You can set capture value to false in order to make a preauthorization with 3D Secure. Then you can void the transaction or do the capture.
2. Pass CryptKey into your frontend code
The preferred method to achieve this would be to send a request to your backend. But you could include the CryptKey value somewhere in your HTML code.
3. Encrypt the card data and send it directly to Straal API
A request containing card data should have the following format:
{ "name": "John Smith", "number": "4444444444444448", "cvv": "123", "expiry_month": 11, "expiry_year": 2021, "billing_address": { "street_addr": "Plac Defilad 1", "postal_code": "00-901", "city": "Warszawa", "country": "Polska", "country_code": "PL" } }
Billing address is optional, but can be required for some merchant types with particular acquirers.
The response body will contain a request_id field which should be matched later on with the threeds_redirection and request_finished notifications.
{ "request_id": "0e04ead77926441c9369f1932ddd13c8" }
4. Redirect your customer to the provided URL
If the request is successful (status code 200), you will receive a threeds_redirection notification along with the response. Redirect your customer to the given redirect_url to proceed the 3D-Secure verification process. Check how does the threeds_redirection notification looks like.
If you are using Straal.js, it will automatically redirect your customer.After the 3D-Secure verification is finished, your customer will be redirected back to one of the specified URLs (success_url or failure_url) depending on the outcome of the 3D-Secure verification.
5. Wait for the request_finished notification on your backend (>>>you need to set up the notification endpoint URL for your account in the Kompas panel). This notification will contain the final state of this payment.
Please note that we send the request finished notification for all transaction-related requests (which means for majority of POST requests to our API). Filter out the relevant notifications by checking the permission field, which in this flow is v1.transactions.create_with_card_3ds.
The request_finished notification for the 3DS transaction will have permission field set to v1.transactions.create_with_card_3ds and the response object will be the final state of the transaction object that was created in the encrypted request from the front-end. In the data you will also find request_id of the front-end request as well as cryptkey ID that was used.
The request_finished notification for the 3DS transaction will have the following format. A successful 3DS transaction will be authorized and the authentication_3ds will have status "succeeded". If you requested a captured transaction, which is the default, it should also be captured.
{ "event": "request_finished", "data": { "path": "/v1/customers/mzivhql5yi9rf/transactions_3ds", "permission": "v1.transactions.create_with_card_3ds", "auth_method": "cryptkey", "cryptkey": { "id": "70xfzmynzgkih" }, "request_id": "0e04ead77926441c9369f1932ddd13c8", "response": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": true, "created_at": 1470238921, "amount": 999, "currency": "usd", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "qkymdfy2jbui1", "created_at": 1470239156, "amount": 999 } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "authentication_3ds": { "id": "8dc41dh1drlqm", "status": "succeeded", "created_at": 1606128812, "failure_url": "http://www.example.merchant_url/fail", "success_url": "http://www.example.merchant_url/success", "threeds_params": null, "protocol_version": "1.0", "enrollment_status": "Y", "eci": "05", "threeds_flow": "frictionless", "errors": [], "threeds_v2": null }, "decline_reason": null, "extra_data": {} } } }
{ "event": "request_finished", "data": { "path": "/v1/customers/mzivhql5yi9rf/transactions_3ds", "permission": "v1.transactions.create_with_card_3ds", "auth_method": "cryptkey", "cryptkey": { "id": "70xfzmynzgkih" }, "request_id": "0e04ead77926441c9369f1932ddd13c8", "response": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": true, "created_at": 1470238921, "amount": 999, "currency": "usd", "authorized": false, "captured": false, "captures": [], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "authentication_3ds": { "id": "1q43cj6o3w8qv", "status": "succeeded", "created_at": 1606134039, "failure_url": "http://www.example.merchant_url/fail", "success_url": "http://www.example.merchant_url/success", "threeds_params": null, "protocol_version": "1.0", "enrollment_status": "Y", "errors": [], "threeds_v2": null }, "decline_reason": { "code": 1002, "description": "Insufficient funds" }, "extra_data": {} } } }
Create a 3DS transaction with the Google Pay using CryptKey
Learn below how to perform a Google Pay transaction with 3D Secure by sending PaymentData from Google directly from website frontend code.By performing the steps below you will register a Google Pay Tokenized Card and perform a $9.99 transaction on it, protected by 3D Secure protocol.
1. Create CryptKey with v1.transactions.create_with_card permission
It has to be done from your application backend, and the request has to be authorized by an APIKey with the correct permission. Transaction details have to be sent along with create CryptKey request. Similarly to server-to-server variant, you need to provide customer result URLs to your transaction data. Since this method is always executed within the customer context, you have to also include customer_id in the request payload. Sample request:
{ "permission": "v1.transactions.create_with_card", "customer_id": "auIj01kcj98lfq", "transaction": { "amount": 999, "currency": "usd", "capture": true, "type": "oneclick", "reference": "b138bc50148440ee", "extra_data": { "key": "value" }, "authentication_3ds": { "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "threeds_v2": { "browser": { "accept_header": "*/*", "color_depth": 24, "java_enabled": false, "language": "pl-PL", "screen_height": 1080, "screen_width": 1920, "timezone": -60, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "ip": "213.120.141.140" } } } } }
You can set capture value to false in order to make a preauthorization with 3D Secure. Then you can void the transaction or do the capture.
reference and extra_data are optional, authentication_3ds is required.
Browser part of 3DS v2 parameters is optional in this request, but if not provided, Browser object should be included in encrypted payload as described in step 3.
2. Pass CryptKey into your frontend code
The preferred method to achieve this would be to send a request to your backend. But you could include the CryptKey value somewhere in your HTML code.
3. Encrypt Google Pay data received from Google and send it directly to Straal API
A request containing card data should have the following format:
{ "type": "google_pay", "origin_ipaddr": "91.17.133.219", "payment_data": { "apiVersion": 2, "apiVersionMinor": 0, "email": "[email protected]", "paymentMethodData": { "type": "CARD", "description": "Visaxxxx1234", "info": { "cardNetwork": "VISA", "cardDetails": "1234" }, "tokenizationData": { "type": "PAYMENT_GATEWAY", "token": "examplePaymentMethodToken" } } }, "browser": { "color_depth": 24, "java_enabled": false, "language": "pl-PL", "screen_height": 1080, "screen_width": 1920, "timezone": -60 } }
Browser part of 3DS v2 parameters can be send in request body instead of adding it at the create CryptKey step. If no accept_header, ip and/or user_agent Browser params will be provided, they will be taken from appropriate headers of encrypted request.
The response body will contain a request_id field which should be matched later on with the request_finished notification.
{ "request_id": "0e04ead77926441c9369f1932ddd13c8" }
4. Redirect your customer to the provided URL
If the request is successful (status code 200), you will receive a Location header along with the response. Redirect your customer to this URL for him to complete the 3D-Secure verification process.
If you are using Straal.js, it will automatically redirect your customer. After the 3D-Secure verification is finished, your customer will be redirected back to one of the specified URLs (success_url or failure_url) depending on the outcome of the 3D-Secure verification.
5. Wait for the request_finished notification on your backend (>>>you need to set up the notification endpoint URL for your account in the Kompas panel). This notification will contain the final state of this payment. Please note that we send the request finished notification for all transaction-related requests (which means for majority of POST requests to our API). Filter out the relevant notifications by checking the permission field, which in this flow is v1.transactions.create_with_card.
The request_finished notification for the 3DS transaction will have permission field set to v1.transactions.create_with_card and the response object will be the final state of the transaction object that was created in the encrypted request from the front-end. In the data you will also find request_id of the front-end request as well as cryptkey ID that was used.
The request_finished notification for the 3DS transaction will have the following format. A successful 3DS transaction will be authorized and the authentication_3ds will have status "succeeded". If you requested a captured transaction, which is the default, it should also be captured.
{ "data": { "path": "/v1/encrypted", "cryptkey": { "id": "657jadm3ag0rv" }, "response": { "id": "djj7x6kruvorv", "voids": [], "amount": 999, "method": "google_pay", "voided": false, "refunds": [], "attempts": [], "captured": true, "captures": [ { "id": "7pr11jyrvdpr6", "amount": 999, "status": "succeeded", "created_at": 1687505118, "extra_data": {} } ], "currency": "usd", "pre_auth": false, "refunded": false, "reference": "REF1687505115", "authorized": true, "chargeback": null, "created_at": 1687505118, "extra_data": {}, "google_pay": { "id": "d47ju70r9avr6", "type": "google_pay", "brand": "visa", "num_bin": "492991", "customer": { "id": "6nf7tj5wrl2rd", "last_transaction": { "id": "djj7x6kruvorv" } }, "created_at": 1689073134, "num_last_4": "6345", "expiry_year": 2023, "expiry_month": 11, "origin_ipaddr": "91.17.133.219" }, "decline_reason": null, "order_reference": null, "with_3ds_params": true, "authentication_3ds": { "id": "vwnf7b3rjd6rt", "eci": "05", "errors": [], "status": "succeeded", "created_at": 1687505118, "threeds_v2": { "browser": { "ip": "213.120.141.140", "language": "pl-PL", "timezone": -300, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "color_depth": 32, "java_enabled": "true", "screen_width": 1440, "accept_header": "*/*", "screen_height": 900, "javascript_enabled": true } }, "failure_url": "http://www.example.merchant_url/fail", "success_url": "http://www.example.merchant_url/success", "threeds_flow": "frictionless", "protocol_version": "2.1.0", "enrollment_status": "Y" }, "external_reference": "298756cf16a585af9a9e5e09fb818f91", "straal_custom_data": {} }, "permission": "v1.transactions.create_with_card", "request_id": "1ab9717c119711ee86690242ac1d000b", "auth_method": "cryptkey", "http_status_code": 200 }, "event": "request_finished" }
{ "data": { "path": "/v1/encrypted", "cryptkey": { "id": "76jtvjfjml7r6" }, "response": { "id": "lt7jfj45m4mr6", "voids": [], "amount": 999, "errors": [ { "code": 60001, "message": "Authorization failed" }, { "code": 17015, "message": "3DS authentication failed" } ], "method": "google_pay", "voided": false, "refunds": [], "attempts": [], "captured": false, "captures": [ { "id": "7hsjcyx5mz6rl", "amount": 999, "status": "failed", "created_at": 1687505529, "extra_data": {} } ], "currency": "usd", "pre_auth": false, "refunded": false, "reference": "REF1687505527", "authorized": false, "chargeback": null, "created_at": 1687505529, "extra_data": {}, "google_pay": { "id": "d47ju70r9avr6", "type": "google_pay", "brand": "visa", "num_bin": null, "customer": { "id": "6nf7tj5wrl2rd", "last_transaction": { "id": "djj7x6kruvorv" } }, "created_at": 1687505529, "num_last_4": null, "expiry_year": null, "expiry_month": null, "origin_ipaddr": "91.17.133.219" }, "decline_reason": { "code": 1006, "description": "Invalid card data" }, "order_reference": null, "with_3ds_params": false, "authentication_3ds": { "id": "mcxg76v5tljr1", "eci": null, "errors": [ { "code": 17015, "message": "3DS authentication failed" } ], "status": "failed", "created_at": 1687505529, "threeds_v2": { "browser": { "ip": "213.120.141.140", "language": "pl-PL", "timezone": -300, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "color_depth": 32, "java_enabled": "true", "screen_width": 1440, "accept_header": "*/*", "screen_height": 900, "javascript_enabled": true } }, "failure_url": "http://www.example.merchant_url/fail", "success_url": "http://www.example.merchant_url/success", "redirect_url": "http://www.example.merchant_url/fail", "threeds_flow": null, "protocol_version": "2.1.0", "enrollment_status": "U" }, "external_reference": "298756cf16a585af9a9e5e09fb818f91", "straal_custom_data": {} }, "permission": "v1.transactions.create_with_card", "request_id": "0fa287b4119811eea4b40242ac1d000b", "auth_method": "cryptkey", "http_status_code": 402 }, "event": "request_finished" }
Create a 3DS transaction with the Apple Pay using CryptKey
Learn below how to perform an Apple Pay transaction with 3D Secure by sending ApplePayPayment from Apple directly from website frontend code.By performing the steps below you will register an Apple Pay Tokenized Card and perform a $9.99 transaction on it, protected by 3D Secure protocol.
1. Create CryptKey with v1.transactions.create_with_card permission
It has to be done from your application backend, and the request has to be authorized by an APIKey with the correct permission. Transaction details have to be sent along with create CryptKey request. Similarly to server-to-server variant, you need to provide customer result URLs to your transaction data. Since this method is always executed within the customer context, you have to also include customer_id in the request payload. Sample request:
{ "permission": "v1.transactions.create_with_card", "customer_id": "auIj01kcj98lfq", "transaction": { "amount": 999, "currency": "usd", "capture": true, "type": "oneclick", "reference": "b138bc50148440ee", "extra_data": { "key": "value" }, "authentication_3ds": { "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "threeds_v2": { "browser": { "accept_header": "*/*", "color_depth": 24, "java_enabled": false, "language": "pl-PL", "screen_height": 1080, "screen_width": 1920, "timezone": -60, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "ip": "213.120.141.140" } } } } }
You can set capture value to false in order to make a preauthorization with 3D Secure. Then you can void the transaction or do the capture.
reference and extra_data are optional, authentication_3ds is required.
Browser part of 3DS v2 parameters is optional in this request, but if not provided, Browser object should be included in encrypted payload as described in step 3.
2. Pass CryptKey into your frontend code
The preferred method to achieve this would be to send a request to your backend. But you could include the CryptKey value somewhere in your HTML code.
3. Encrypt Apple Pay data received from Apple and send it directly to Straal API
A request containing card data should have the following format:
{ "type": "apple_pay", "origin_ipaddr": "91.17.133.219", "payment_data": { "token": { "paymentData": { "data": "oSXLIUh9dmJK6D3nB1I3BKabO1hF3n+ScnQYw==", "signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDAAAAAAAA", "header": { "publicKeyHash": "Mjiu4PLiqVUKhKO5bX55JoNA1VMN2kIRIzPF8XV0cfc=", "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj==", "transactionId": "88e209d0c9ad440b4442857e562c796b3e759871" }, "version": "EC_v1" }, "paymentMethod": { "displayName": "MasterCard 1234", "network": "MasterCard", "type": "credit" }, "transactionIdentifier": "88E209D0C9AD440BC9C319FC7C24AB6E7" }, "billingContact": { "familyName": "", "givenName": "", "phoneticFamilyName": "", "phoneticGivenName": "" } }, "browser": { "color_depth": 24, "java_enabled": false, "language": "pl-PL", "screen_height": 1080, "screen_width": 1920, "timezone": -60 } }
Browser part of 3DS v2 parameters can be sent in request body instead of adding it at the create CryptKey step. If no accept_header, ip and/or user_agent Browser params will be provided, they will be taken from appropriate headers of encrypted request.
The response body will contain a request_id field which should be matched later on with the request_finished notification.
{ "request_id": "0e04ead77926441c9369f1932ddd13c8" }
4. Redirect your customer to the provided URL
If the request is successful (status code 200), you will receive a Location header along with the response. Redirect your customer to this URL for him to complete the 3D-Secure verification process.
If you are using Straal.js, it will automatically redirect your customer. After the 3D-Secure verification is finished, your customer will be redirected back to one of the specified URLs (success_url or failure_url) depending on the outcome of the 3D-Secure verification.
5. Wait for the request_finished notification on your backend (>>>you need to set up the notification endpoint URL for your account in the Kompas panel). This notification will contain the final state of this payment. Please note that we send the request finished notification for all transaction-related requests (which means for majority of POST requests to our API). Filter out the relevant notifications by checking the permission field, which in this flow is v1.transactions.create_with_card.
The request_finished notification for the 3DS transaction will have permission field set to v1.transactions.create_with_card and the response object will be the final state of the transaction object that was created in the encrypted request from the front-end. In the data you will also find request_id of the front-end request as well as cryptkey ID that was used.
The request_finished notification for the 3DS transaction will have the following format. A successful 3DS transaction will be authorized and the authentication_3ds will have status "succeeded". If you requested a captured transaction, which is the default, it should also be captured.
{ "data": { "path": "/v1/encrypted", "cryptkey": { "id": "657jadm3ag0rv" }, "response": { "id": "djj7x6kruvorv", "voids": [], "amount": 999, "method": "apple_pay", "voided": false, "refunds": [], "attempts": [], "captured": true, "captures": [ { "id": "7pr11jyrvdpr6", "amount": 999, "status": "succeeded", "created_at": 1687505118, "extra_data": {} } ], "currency": "usd", "pre_auth": false, "refunded": false, "reference": "REF1687505115", "authorized": true, "chargeback": null, "created_at": 1687505118, "extra_data": {}, "apple_pay": { "id": "d47ju70r9avr6", "type": "apple_pay", "brand": "mastercard", "num_bin": null, "customer": { "id": "6nf7tj5wrl2rd", "last_transaction": { "id": "djj7x6kruvorv" } }, "created_at": 1689073134, "num_last_4": "1234", "expiry_year": 2023, "expiry_month": 11, "origin_ipaddr": "91.17.133.219" }, "decline_reason": null, "order_reference": null, "with_3ds_params": true, "authentication_3ds": { "id": "vwnf7b3rjd6rt", "eci": "05", "errors": [], "status": "succeeded", "created_at": 1687505118, "threeds_v2": { "browser": { "ip": "213.120.141.140", "language": "pl-PL", "timezone": -300, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "color_depth": 32, "java_enabled": "true", "screen_width": 1440, "accept_header": "*/*", "screen_height": 900, "javascript_enabled": true } }, "failure_url": "http://www.example.merchant_url/fail", "success_url": "http://www.example.merchant_url/success", "threeds_flow": "frictionless", "protocol_version": "2.1.0", "enrollment_status": "Y" }, "external_reference": "298756cf16a585af9a9e5e09fb818f91", "straal_custom_data": {} }, "permission": "v1.transactions.create_with_card", "request_id": "1ab9717c119711ee86690242ac1d000b", "auth_method": "cryptkey", "http_status_code": 200 }, "event": "request_finished" }
{ "data": { "path": "/v1/encrypted", "cryptkey": { "id": "76jtvjfjml7r6" }, "response": { "id": "lt7jfj45m4mr6", "voids": [], "amount": 999, "errors": [ { "code": 60001, "message": "Authorization failed" }, { "code": 17015, "message": "3DS authentication failed" } ], "method": "apple_pay", "voided": false, "refunds": [], "attempts": [], "captured": false, "captures": [ { "id": "7hsjcyx5mz6rl", "amount": 999, "status": "failed", "created_at": 1687505529, "extra_data": {} } ], "currency": "usd", "pre_auth": false, "refunded": false, "reference": "REF1687505527", "authorized": false, "chargeback": null, "created_at": 1687505529, "extra_data": {}, "apple_pay": { "id": "d47ju70r9avr6", "type": "apple_pay", "brand": "mastercard", "num_bin": null, "customer": { "id": "6nf7tj5wrl2rd", "last_transaction": { "id": "djj7x6kruvorv" } }, "created_at": 1687505529, "num_last_4": null, "expiry_year": null, "expiry_month": null, "origin_ipaddr": "91.17.133.219" }, "decline_reason": { "code": 1006, "description": "Invalid card data" }, "order_reference": null, "with_3ds_params": false, "authentication_3ds": { "id": "mcxg76v5tljr1", "eci": null, "errors": [ { "code": 17015, "message": "3DS authentication failed" } ], "status": "failed", "created_at": 1687505529, "threeds_v2": { "browser": { "ip": "213.120.141.140", "language": "pl-PL", "timezone": -300, "user_agent": "Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)", "color_depth": 32, "java_enabled": "true", "screen_width": 1440, "accept_header": "*/*", "screen_height": 900, "javascript_enabled": true } }, "failure_url": "http://www.example.merchant_url/fail", "success_url": "http://www.example.merchant_url/success", "redirect_url": "http://www.example.merchant_url/fail", "threeds_flow": null, "protocol_version": "2.1.0", "enrollment_status": "U" }, "external_reference": "298756cf16a585af9a9e5e09fb818f91", "straal_custom_data": {} }, "permission": "v1.transactions.create_with_card", "request_id": "0fa287b4119811eea4b40242ac1d000b", "auth_method": "cryptkey", "http_status_code": 402 }, "event": "request_finished" }
3DS v2 request parameters
Below is the structure of threeds_v2 object. There are many parameters, but only a little number of them is required. The more information is provided, the bigger chances of having frictionless authorisation or detecting fraudulent transaction.Possible values:
01 - Goods/ Service Purchase
03 - Check Acceptance
10 - Account Funding
11 - Quasi-Cash Transaction
28 - Prepaid Activation and Load
Examples:
- for Payment Authentication, a 3DS Requestor may have concerns about the transaction, and request a challenge.
- for Non Payment Authentication, a challenge may be necessary when adding a new card to a wallet.
- for local/regional mandates or other variables.
01 - No preference
02 - No challenge requested
03 - Challenge requested (3DS Requestor preference)
04 - Challenge requested (Mandate)
05 - No challenge requested (transactional risk analysis is already performed)
06 - No challenge requested (Data share only)
07 - No challenge requested (strong consumer authentication is already performed)
08 - No challenge requested (utilise whitelist exemption if no challenge required)
09 - Challenge requested (whitelist prompt requested if challenge required)
Possible values:
01 - Low value exemption
02 - TRA Exemption
03 - Trusted beneficiary exemption
04 - Corporate card payment exemption
05 - For recurring transactions
06 - For MIT
07 - For MOTO
CardholderAccountInformation object - additional information about the Cardholder’s account provided by the 3DS Requestor.
01 - No account (guest check-out)
02 - Created during this transaction
03 - Less than 30 days
04 - 30−60 days
05 - More than 60 days
Length: 8 characters
Format accepted: YYYYMMDD
Possible values:
01 - Changed during this transaction
02 - Less than 30 days
03 - 30−60 days
04 - More than 60 days
Length: 8 characters
Format accepted: YYYYMMDD
Length: 8 characters
Format accepted: YYYYMMDD
Possible values:
01 - No change
02 - Changed during this transaction
03 - Less than 30 days
04 - 30−60 days
05 - More than 60 days
Length: maximum 4 characters
Example values:
- 2
- 02
- 002
Length: maximum 3 characters
Length: 8 characters
Format accepted: YYYYMMDD
Possible values:
01 - No account (guest check-out)
02 - During this transaction
03 - Less than 30 days
04 - 30−60 days
05 - More than 60 days
Length: 8 characters
Format accepted: YYYYMMDD
Possible values:
01 - This transaction
02 - Less than 30 days
03 - 30−60 days
04 - More than 60 days
Possible values:
01 - Account Name identical to shipping Name
02 - Account Name different than shipping Name
Possible values:
01 - No suspicious activity has been observed
02 - Suspicious activity has been observed
The structure of Browser object:
Length: Variable, maximum 2048 characters
Value accepted: If the total length of the accept header sent by the browser exceeds 2048 characters, the 3DS Server truncates the excess portion
Conditional: Shall include this field where regionally acceptable
Length: Variable, maximum 45 characters
Values accepted:
- IPv4 address is represented in the dotted decimal format of 4 sets of decimal numbers separated by dots.
The decimal number in each and every set is in the range 0 to 255.
Example IPv4 address: 1.12.123.255 - IPv6 address is represented as eight groups of four hexadecimal digits, each group representing 16 bits (two octets. The groups are separated by colons (:). Example IPv6 address:2011:0db8:85a3:0101:0101:8a2e:0370:7334
Returned from navigator.language property.
Length: Variable, 1–8 characters
Length: Variable, maximum 2048 characters
Value accepted: Note: If the total length of the User-Agent sent by the browser exceeds 2048 characters, the 3DS Server truncates the excess portion.
Obtained from Cardholder browser using the screen.colorDepth property.
Conditional: Required when Browser JavaScript Enabled = true; otherwise Optional.
Value is returned from the screen.height property.
Conditional: Required when Browser JavaScript Enabled = true; otherwise Optional.
Length: Variable, 1–6 characters; Numeri
Value is returned from the screen.width property.
Conditional: Required when Browser JavaScript Enabled = true; otherwise Optional.
Length: Variable, 1–6 characters; Numeric
Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead.
Conditional: Required when Browser JavaScript Enabled = true; otherwise Optional.
Length: Variable, 1–5 characters
Value accepted: Value is returned from the getTimezoneOffset() method.
Example time zone offset values in minutes:
If UTC -5 hours:
- 300
- +300
If UTC +5 hours:
- 300
Length: Variable, up to 64 characters
This identifier is a unique immutable hash of the user’s account identifier for the given Browser, provided as a string.
Note: Cardholders may have more than one account on a given Browser.
Length: Variable, maximum 64 characters
MerchantRiskIndicator object - merchant’s assessment of the level of fraud risk for the specific authentication for both the cardholder and the authentication being conducted.
Length: maximum 254 characters
Possible values:
01 - Electronic Delivery
02 - Same day shipping
03 - Overnight shipping
04 - Two - day or more shipping
Example: gift card amount is USD 123.45
Values accepted:
- 123
- 0123
- 00123
Length: maximum 15 characters
Length: 2 characters
Length: 3 characters; numeric
Length: 8 characters
Format accepted: YYYYMMDD
Possible values:
01 - Merchandise available
02 - Future availability
Possible values:
01 - First time ordered
02 - Reordered
01 - Ship to cardholder’s billing address
02 - Ship to another verified address on file with merchant
03 - Ship to address that is different than the cardholder’s billing address
04 - “Ship to Store” / Pick-up at local store (Store address shall be populated in shipping address fields)
05 - Digital goods (includes online services, electronic gift cards and redemption codes)
06 - Travel and Event tickets, not shipped
07 - Other (for example, Gaming, digital services not shipped, emedia subscriptions, etc.)
3DS v2 flows
-
The merchant submits a 3DSecure transaction (authentication_3ds object) to Straal API, including the 3DSecure v2 params (threeds_v2 object). If the card is not valid a response will be returned, indicating the error.
-
Card issuer responds to Straal with one of possible 3DSecure v2 flows: Frictionless, Challenge or Fallback. All flows are covered by Straal.
-
Frictionless - no challenge or additional methods are required by the card issuer, the authentication has been done positively, and the transaction will be completed without further action.
-
Challenge - the card issuer determines that the transaction requires additional cardholder authentication. The customer is redirected by Straal to an URL provided by the acquirer. After the required interaction is complete, the customer is redirected to the failure or success urls.
-
Fallback - the card issuer enforces fallback to 3DSecure v1 protocol. After the required interaction is complete, the customer is redirected to the failure or success urls.
-
3DSecure method - is performed by Straal for you in a background. 3DSecure Method is required to gather additional information about customer via their browser. 3D Secure Method helps to identify when transaction is a low risk and can be processed without required customer interaction (frictionless)
-
Frictionless - no challenge or additional methods are required by the card issuer, the authentication has been done positively, and the transaction will be completed without further action.
- A synchronous payment response is returned to the merchant, indicating the status of the payment. Also, an asynchronous notification to notification URL is enqueued (HTTP POST).
Create a transaction with a card
This method allows you to create a card and perform a transaction on it in one request.type can take values oneshot, oneclick or recurring.
{ "amount": 999, "currency": "usd", "reference": "b138bc50148440ee", "type": "oneshot", "order_reference": null, "card": { "name": "John Smith", "number": "4444444444444448", "cvv": "123", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "91.17.133.219" } }
{ "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "usd", "method": "card", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "qkymdfy2jbui1", "created_at": 1470239156, "amount": 999 } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "mzivhql5yi9rf", "created_at": 1467906605, "state": "active", "state_flags": [], "brand": "visa", "name": "John Smith", "num_bin": "444444", "num_last_4": "4448", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "91.17.133.219", "customer": { "id": "mhtaqdb4edvrf" }, "extra_data": {} }, "decline_reason": null, "extra_data": {} }
Create a transaction with a card using CryptKey
The purpose of this method is to perform a transaction by sending sensitive data directly from a mobile application or website frontend code, so no card data will hit your servers, which results in improved security and fewer PCI compliance requirements.By performing the steps below you will register a card and perform a $9.99 transaction on it.
1. Create CryptKey with v1.transactions.create_with_card permission
It has to be done from your application backend, and the request has to be authorized by an APIKey with the correct permission. Transaction details have to be sent along with create CryptKey request. Since this method is always executed within the customer context, you have to also include customer_id in the request payload. Sample request:
{ "permission": "v1.transactions.create_with_card", "customer_id": "auIj01kcj98lfq", "transaction": { "amount": 999, "currency": "usd", "reference": "b138bc50148440ee", "type": "oneclick", "extra_data": { "key": "value" } } }
2. Pass CryptKey into your frontend code
The preferred method to achieve this would be to send a request to your backend. But you could include the CryptKey value somewhere in your HTML code.
3. Encrypt the card data and send it directly to Straal API
{ "name": "John Smith", "number": "4444444444444448", "cvv": "123", "expiry_month": 11, "expiry_year": 2023 }
Response body will contain only request_id which should be matched with request_finished notification.
{ "request_id": "db7a6a7c37c949f78acb563427456ee3" }
Create a transaction with merchant risk params
You can also add parameters relating to the purpose of the transaction. This needs to be configured ahead of time, and is required for some merchant types with particular acquirers. Contact Straal support to determine which parameters are required for your use case. merchant_risk_params can be included in any card transaction request.merchant_risk_params object:
Example request using create a transaction endpoint
{ "amount": 999, "currency": "usd", "reference": "b138bc50148440yy", "type": "oneclick", "merchant_risk_params": { "departure_date": "2021-01-13", "arrival_date": "2021-01-18" } }
{ "id": "p4sacj0gl5r7c", "card": { "id": "wjyjp7c87wp7c", "customer": { "id": "j9ubc9jou7c7a", "last_transaction": { "id": "p4sacj0gl5r7c" } } }, "captures": [ { "id": "jyjcbrrtphc75", "created_at": 1592302456, "amount": 999, "status": "succeeded", "extra_data": {} } ], "refunds": [], "voids": [], "attempts": [], "with_3ds_params": false, "created_at": 1592302452, "amount": 999, "currency": "usd", "authorized": true, "pre_auth": false, "captured": true, "refunded": false, "extra_data": {}, "straal_custom_data": {}, "chargeback": null, "reference": "b138bc50148440yy", "external_reference": null, "order_reference": null, "decline_reason": null, "voided": false, "method": "card", "merchant_risk_params": { "departure_date": "2021-01-13", "arrival_date": "2021-01-18" } }
Get a transaction
Returns details of an existing transaction.If transaction was authorized with 3D-Secure, authentication_3ds details will be available.
{ "id": "5nffaefhmlc6h", "attempts": [], "with_3ds_params": true, "created_at": 1472491810, "authentication_3ds": { "id": "688xc7ogyc5ja", "success_url": "https://your.website.url/success", "failure_url": "https://your.website.url/failure", "status": "succeeded", "created_at": 1472491822, "enrollment_status": "Y", "eci": "05", "threeds_flow": "frictionless", "errors": [] }, "amount": 999, "currency": "usd", "method": "card", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "mkwsfft8hn66y", "created_at": 1472473029, "amount": 999 } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "5nffaefhmlc6h", "customer": { "id": "mhtaqdb4edvrf" } }, "decline_reason": null, "extra_data": {} }
Get a list of transactions
Returns a list of transactions for the merchant's account.If transaction was authorized with 3D-Secure, authentication_3ds details will be available.
GET /v1/transactions?per_page=2&page=1
{ "data": [ { "id": "5nffaefhmlc6h", "attempts": [], "with_3ds_params": true, "created_at": 1472491810, "authentication_3ds": { "id": "688xc7ogyc5ja", "success_url": "https://your.website.url/success", "failure_url": "https://your.website.url/failure", "status": "succeeded", "created_at": 1472491822, "enrollment_status": "Y", "errors": [] }, "amount": 999, "currency": "usd", "method": "card", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "mkwsfft8hn66y", "created_at": 1472473029, "amount": 999 } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "5nffaefhmlc6h", "customer": { "id": "mhtaqdb4edvrf" } }, "decline_reason": null, "extra_data": {} }, { "id": "xdn0ffvrjxf6v", "attempts": [], "with_3ds_params": false, "created_at": 1472380727, "amount": 1599, "currency": "eur", "authorized": true, "pre_auth": false, "captured": false, "captures": [], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": null, "external_reference": null, "order_reference": "1495d2e44a11407b", "card": { "id": "fqovkf4k5bsbn", "customer": { "id": "sj7uj23shqf" } }, "decline_reason": null, "extra_data": {} } ], "page": 1, "per_page": 2, "total_count": 2 }
Get a list of customer transactions
Returns a list of transactions for a specified customer ID.GET /v1/customers/mhtaqdb4edvrf/transactions?per_page=2&page=1
{ "data": [ { "id": "5nffaefhmlc6h", "attempts": [], "with_3ds_params": false, "created_at": 1472491810, "amount": 999, "currency": "usd", "method": "card", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "mkwsfft8hn66y", "created_at": 1472473029, "amount": 999 } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "5nffaefhmlc6h" }, "decline_reason": null, "extra_data": {} }, { "id": "xdn0ffvrjxf6v", "attempts": [], "with_3ds_params": false, "created_at": 1472380727, "amount": 1599, "currency": "eur", "method": "card", "authorized": true, "pre_auth": false, "captured": false, "captures": [], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "1495d2e44a11407b", "external_reference": null, "order_reference": null, "card": { "id": "fqovkf4k5bsbn" }, "decline_reason": null, "extra_data": {} } ], "page": 1, "per_page": 2, "total_count": 2 }
Get transactions for a given card
Returns a list of transactions for a specified card ID.GET /v1/cards/5nffaefhmlc6h/transactions?per_page=2&page=1
{ "data": [ { "id": "5nffaefhmlc6h", "attempts": [], "with_3ds_params": false, "created_at": 1472491810, "amount": 999, "currency": "usd", "method": "card", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "mkwsfft8hn66y", "created_at": 1472473029, "amount": 999 } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "decline_reason": null, "extra_data": {} }, { "id": "xdn0ffvrjxf6v", "attempts": [], "with_3ds_params": false, "created_at": 1472380727, "amount": 1599, "currency": "eur", "method": "card", "authorized": true, "pre_auth": false, "captured": false, "captures": [], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "1495d2e44a11407b", "external_reference": null, "order_reference": null, "decline_reason": null, "extra_data": {} } ], "page": 1, "per_page": 2, "total_count": 2 }
Get transactions for a given subscription
Returns a list of transactions for a specified subscription ID.GET /v1/subscriptions/m5lwrskt18r4f/transactions?per_page=2&page=1
{ "data": [ { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "usd", "method": "card", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "mkwsfft8hn66y", "created_at": 1472473029, "amount": 999 } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "5nffaefhmlc6h", "customer": { "id": "mhtaqdb4edvrf" } }, "decline_reason": null, "extra_data": {} }, { "id": "xdn0ffvrjxf6v", "attempts": [], "with_3ds_params": false, "created_at": 1472380727, "amount": 999, "currency": "usd", "method": "card", "authorized": true, "pre_auth": false, "captured": false, "captures": [], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "1495d2e44a11407b", "external_reference": null, "order_reference": null, "card": { "id": "5nffaefhmlc6h", "customer": { "id": "mhtaqdb4edvrf" } }, "decline_reason": null, "extra_data": {} } ], "page": 1, "per_page": 2, "total_count": 2 }
3D-Secure Authentications
These resources allow you to perform a transaction with 3D-Secure authentication.3D-Secure authentication object attributes
Below is the structure of authentication_3ds object.[DEPRECATED] 3D-Secure payment process overview
The 3DSecure payment process described below is now deprecated. Please refer to the overview of the new flow using CryptKeys or server-to-server integration (see our quick reference of PCI SAQ types to get help with choosing the best way of integration for your business).- Initialize the 3D-Secure process.
- Customer is redirected to their issuing bank for the purpose of Strong Customer Authentication (SCA).
- After the customer has authenticated themselves with their issuing bank they will be redirected to one of the URLs provided in step 1.
- Redirection to success_url does not mean the transaction was processed successfully, only that the customer has successfully authenticated with his bank.
- A request_finished notification will be sent to your backend, containing the details of the authentication attempt.
- Up to this point, only the Strong Customer Authentication (SCA) step has been completed, no transaction has been made and no money has been transferred.
- Finalize the transaction - this will create a transaction and charge the card.
[DEPRECATED] Initialize 3D-Secure process with a CryptKey
This method allows you to initialize the 3D-Secure process using a CryptKey.1. Create a CryptKey with v1.customers.authentications_3ds.init_3ds permission
Sample request:
{ "permission": "v1.customers.authentications_3ds.init_3ds", "customer_id": "auIj01kcj98lfq", "transaction": { "amount": 999, "currency": "EUR", "reference": "b138bc50148440ee", "success_url": "https://your.website.url/success", "failure_url": "https://your.website.url/failure", "extra_data": { "key": "value" } } }
2. Pass CryptKey into your frontend code
The preferred method to achieve this would be to send a request to your backend. But you could include the CryptKey value somewhere in your HTML code.
3. Encrypt the card data and send it directly to Straal API
A request containing card data should have the following format:
{ "name": "John Smith", "number": "4444444444444448", "cvv": "123", "expiry_month": 11, "expiry_year": 2020 }
{ "request_id": "db7a6a7c37c949f78acb563427456ee3" }
4. Redirect your customer to the provided URL
If the request is successful (status code 200), you will receive a Location header along with the response. Redirect your customer to this URL for him to complete the 3D-Secure verification process.
If you are using Straal.js, it will automatically redirect your customer. After the 3D-Secure verification is finished, your customer will be redirected back to one of the specified URLs (success_url or failure_url) depending on the outcome of the 3D-Secure verification.
5. Wait for the request_finished notification
After you receive the request_finished notification you can complete the transaction.
It should have the following format:
{ "event": "request_finished", "data": { "path": "/v1/customers/auIj01kcj98lfq/authentications_3ds", "permission": "v1.customers.authentications_3ds.init_3ds", "auth_method": "cryptkey", "cryptkey": { "id": "70xfzmynzgkih" }, "request_id": "0e04ead77926441c9369f1932ddd13c8", "response": { "id": "688xc7ogyc5jz", "card": { "id": "6fcx1z5g8n5j7", "customer": { "id": "zqx9cebax67j7" } }, "token_3ds": { "id": "wywcex2r6irjz", "transaction": null }, "created_at": 1558455725, "amount": 999, "currency": "EUR", "reference": "b138bc50148440ee", "success_url": "https://your.website.url/success", "failure_url": "https://your.website.url/failure", "enrollment_status": "Y", "straal_custom_data": {}, "errors": [], "redirect_url": "https://checkout.straal.com/authentications_3ds/some_token" } } }
At this point, the 3D-Secure authentication has been finished, but the transaction has not been completed yet.
Save the value from the id field. You can use it later to query the API about the status of the 3D-Secure authentication or to finalize the transaction.
Get a 3D-Secure authorization
Returns details of an existing 3D-Secure authentication.{ "id": "688xc7ogyc5jz", "card": { "id": "6fcx1z5g8n5j7", "customer": { "id": "zqx9cebax67j7", "last_transaction": {"id": "98mjmc70xnjrb"} } }, "subscription": null, "token_3ds": { "id": "wywcex2r6irjz", "transaction": null }, "created_at": 1558457180, "amount": 999, "currency": "EUR", "reference": "b138bc50148440ee", "success_url": "https://your.merchant.url/success", "failure_url": "https://your.merchant.url/fail", "enrollment_status": "Y", "straal_custom_data": {}, "errors": [] }
[DEPRECATED] Finalize a 3D-Secure transaction
This method allows you to finalize a previously started 3D-Secure authentication process.Sample response:
{ "id": "zlxew7cky9yjd", "card": { "id": "xjpbcb9zy9zje", "customer": { "id": "9qcxlz1ilj0je", "last_transaction": { "id": "zlxew7cky9yjd" } }, "created_at": 1558457393, "brand": "visa", "name": "John Smith", "num_bin": "444444", "num_last_4": "4448", "expiry_month": 1, "expiry_year": 2024, "origin_ipaddr": "91.17.133.219", "extra_data": {}, "state": "active", "state_flags": [] }, "captures": [ { "id": "ziat5x7f79cjg", "created_at": 1558457406, "amount": 999, "status": "succeeded", "extra_data": {} } ], "refunds": [], "voids": [], "attempts": [], "with_3ds_params": true, "created_at": 1558457405, "amount": 999, "currency": "eur", "authorized": true, "pre_auth": false, "captured": true, "refunded": false, "extra_data": {}, "chargeback": null, "reference": null, "external_reference": null, "order_reference": null, "decline_reason": null, "voided": false, "method": "card" }
Captures
The capture object represents a capture operation performed on previously authorised transaction. You can capture transactions that were successfully authorized and haven't been captured yet. Capture operation can be performed up to 48 hours after the successful authorization.Capture object attributes
Create a full capture
This method allows you to perform a capture on a previously authorised transaction. The capture method returns the transaction object that was being captured. If the capture succeeded, the captured attribute on the transaction object is set to true.{ "extra_data": { "custom_field": "value" } }
{ "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "usd", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "qkymdfy2jbui1", "created_at": 1487694077, "amount": 999, "status": "succeeded", "extra_data": { "custom_field": "value" } } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "decline_reason": null, "extra_data": {} }
Create a partial capture
To make a partial capture you have to use the same method as for a full capture. The request body needs to contain the amount that should be transferred from the cardholder account.If the capture succeeded, the captured attribute on the transaction object is set to true.
{ "amount": 499 }
{ "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "usd", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "qkymdfy2jbui1", "created_at": 1487694077, "amount": 499, "status": "succeeded", "extra_data": {} } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "decline_reason": null, "extra_data": {} }
Refunds
The refund object represents a real refund operation performed on a credit card.Refund object attributes
Create a full refund
This method allows you to perform a refund on a previously created transaction. The refund method returns a transaction object that was being refunded. If the full refund succeeded, the refunded attribute on the transaction object is set to true.{ "extra_data": { "reason": "cancellation" } }
{ "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "usd", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "qkymdfy2jbui1" } ], "refunded": true, "refunds": [ { "id": "cz8tteizwf0bv", "created_at": 1487694077, "amount": 999, "status": "succeeded", "extra_data": { "reason": "cancellation" } } ], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "decline_reason": null, "extra_data": {} }
Create a partial refund
To make a partial refund you have to use the same method as for a full refund. The request body needs to contain the amount that should be credited.It is possible to perform more than one partial refund per transaction, as long as their sum does not exceed the original transaction amount. If the sum of partial refunds is equal to the amount of the transaction, the transaction attribute refunded is set to true.
{ "amount": 499 }
{ "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "usd", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "qkymdfy2jbui1" } ], "refunded": false, "refunds": [ { "id": "cz8tteizwf0bv", "created_at": 1487694077, "amount": 499, "status": "succeeded", "extra_data": {} } ], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "decline_reason": null, "extra_data": {} }
Cards
Card is an object which represents a credit card and its ID acts as a token which can be used to perform further transactions.Card object attributes
Verification transaction object attributes
To ensure that the given credit card data is valid, we perform a verification_transaction when handling card object creation requests. By default, during card verification, we authorize and void a small amount from the given credit card. The default amount and currency are configured during the integration phase. To override default verification transaction amount settings, you have to send verification_transaction object in the create card request.Tokenization object attributes
Billing address object attributes
You can add a billing address whenever providing card data. This needs to be configured ahead of time, and is required for some merchant types with particular acquirers. Contact Straal support to determine which address fields are required for your use case.Create a card
Creates a card for a specified customer ID.{ "name": "John Smith", "number": "4444444444444448", "cvv": "123", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "91.17.133.219" }
{ "id": "mzivhql5yi9rf", "created_at": 1467906605, "state": "active", "state_flags": [], "brand": "visa", "name": "John Smith", "num_bin": "444444", "num_last_4": "4448", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "91.17.133.219", "customer": { "id": "mbrudb30nt9rf" }, "extra_data": {} }
{ "name": "John Smith", "number": "4444444444444448", "cvv": "123", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "91.17.133.219", "billing_address": { "street_addr": "Plac Defilad 1", "postal_code": "00-901", "city": "Warszawa", "country": "Polska", "country_code": "PL" } }
{ "id": "mzivhql5yi9rf", "created_at": 1467906605, "state": "active", "state_flags": [], "brand": "visa", "name": "John Smith", "num_bin": "444444", "num_last_4": "4448", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "91.17.133.219", "customer": { "id": "mbrudb30nt9rf" }, "extra_data": {}, "billing_address": { "id": "ubzynjsatr4wz", "street_addr": "Plac Defilad 1", "postal_code": "00-901", "city": "Warszawa", "country": "Polska", "country_code": "PL" } }
Create a card using CryptKey
The purpose of this method is to create a card directly from mobile application or website front end code, so no card data will hit your servers, which results in improved security and fewer PCI compliance requirements.1. Create CryptKey with v1.cards.create permission
It has to be done from your application backend, and the request has to be authorized by an APIKey with the correct permission. Since this method is always executed within the customer context, you have to also include customer_id in the request payload. Sample request:
{ "permission": "v1.cards.create", "customer_id": "auIj01kcj98lfq", "card": { "extra_data": { "key": "value" } } }
You can optionally provide billing address for card. It will be used later even if client will provide billing address from front-end. Sample request:
{ "permission": "v1.cards.create", "customer_id": "auIj01kcj98lfq", "card": { "billing_address": { "street_addr": "Plac Defilad 1", "postal_code": "00-901", "city": "Warszawa", "country": "Polska", "country_code": "PL" } } }
2. Pass CryptKey into your frontend code
The preferred method to achieve this would be to send a request to your backend. But you have to include the CryptKey value somewhere in your HTML code.
3. Encrypt the card data and send it directly to Straal API
{ "name": "John Smith", "number": "4444444444444448", "cvv": "123", "expiry_month": 11, "expiry_year": 2023 }
{ "request_id": "db7a6a7c37c949f78acb563427456ee3" }
Request payload accepts also billing address but if it was provided during creation CryptKey it will be ignored. Example request payload with billing address:
{ "name": "John Smith", "number": "4444444444444448", "cvv": "123", "expiry_month": 11, "expiry_year": 2023, "billing_address": { "street_addr": "Plac Defilad 1", "postal_code": "00-901", "city": "Warszawa", "country": "Polska", "country_code": "PL" } }
Tokenize a card
Merchant may want to use external 3DS server to create a transaction or subscription. To do so, you can start with tokenizing a card, to avoid storing card data during the 3DS process. Then mpi_params can be send when making transaction on previously tokenized card. subscription.Card tokenization can be used both in Create a card and Create a card using CryptKey
Tokenize with Create a card
Creates a tokenized card for a customer. It can be performed by sending tokenization object with purpose: "init_payment" in the request body.
{ "name": "John Smith", "number": "4444444444444448", "cvv": "123", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "91.17.133.219", "tokenization": {"purpose": "init_payment"} }
{ "id": "mzivhql5yi9rf", "created_at": 1467906605, "state": "awaiting_initial_transaction", "state_flags": [], "brand": "visa", "name": "John Smith", "num_bin": "444444", "num_last_4": "4448", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "91.17.133.219", "customer": { "id": "mbrudb30nt9rf" }, "extra_data": {}, "transactions": [ { "amount": 100, "authorized": true, "pre_auth": false, "captured": false, "captures": [], "chargeback": null, "created_at": 1468577590, "currency": "usd", "decline_reason": null, "extra_data": {}, "id": "n4lar14f3a54f", "attempts": [], "with_3ds_params": false, "reference": null, "external_reference": null, "order_reference": null, "refunded": false, "refunds": [], "voided": false, "voids": [] } ] }
Tokenize with CryptKey
Card can be tokenized using CryptKey
Creating tokenized card can be provided by sending tokenization object with purpose: "init_payment" in the request body.
Sample request:
{ "permission": "v1.cards.create", "customer_id": "auIj01kcj98lfq", "card": { "extra_data": { "key": "value" }, "tokenization": {"purpose": "init_payment"} } }
Get a card
Returns information of a specified card.{ "id": "jcjnkqzzupm07", "customer": { "id": "7rsjnvb58lm0p", "last_transaction": { "id": "mntfjug0cp70u", "card": { "id": "jcjnkqzzupm07" } } }, "created_at": 1690969615, "brand": "visa", "name": "John Smith", "num_bin": "444444", "num_last_4": "4448", "expiry_month": 12, "expiry_year": 2025, "origin_ipaddr": "48.118.227.225", "extra_data": {}, "straal_custom_data": {}, "state": "active", "state_flags": [] }
Get the card list
Returns a list of cards for the merchant's account.GET /v1/cards?per_page=3&page=1
{ "data": [ { "id": "sq5g33mh9jf9f", "created_at": 1470090665, "state": "active", "state_flags": [], "brand": "visa", "name": "John Smith", "num_bin": "444444", "num_last_4": "4448", "expiry_month": 10, "expiry_year": 2016, "origin_ipaddr": "123.10.11.12", "customer": { "id": "bq75z9dhfut5k" }, "extra_data": {} }, { "id": "s9b7f7cqsmzd1", "created_at": 1474548758, "state": "active", "state_flags": [], "brand": "visa", "name": "Alan Moore", "num_bin": "424242", "num_last_4": "4242", "expiry_month": 6, "expiry_year": 2023, "origin_ipaddr": "11.99.98.97", "customer": { "id": "k9ibjzfdaoi5c" }, "extra_data": {} }, { "id": "k3n2btvbdrnsq", "created_at": 1474548758, "state": "disabled", "state_flags": [ { "code": 1, "description": "Disabled by customer" } ], "brand": "mastercard", "name": "George Miller", "num_bin": "555555", "num_last_4": "4444", "expiry_month": 1, "expiry_year": 2019, "origin_ipaddr": "22.33.44.100", "customer": { "id": "00khkb5c0q75b" }, "extra_data": {} } ], "page": 1, "per_page": 3, "total_count": 5 }
Get customer's cards
Returns a list of cards assigned to a specified customer ID.GET /v1/customers/znhibktfny95i/cards?per_page=3&page=1
{ "data": [ { "id": "sq5g33mh9jf9f", "created_at": 1470090665, "state": "active", "state_flags": [], "brand": "visa", "name": "George Smith", "num_bin": "444444", "num_last_4": "4448", "expiry_month": 10, "expiry_year": 2016, "origin_ipaddr": "123.10.11.12", "extra_data": {} }, { "id": "k3n2btvbdrnsq", "created_at": 1474548758, "state_flags": [ { "code": 1, "description": "Disabled by customer" } ], "brand": "mastercard", "name": "George Smith", "num_bin": "555555", "num_last_4": "4444", "expiry_month": 1, "expiry_year": 2019, "origin_ipaddr": "22.33.44.100", "extra_data": {} } ], "page": 1, "per_page": 3, "total_count": 2 }
Mark card disabled
Marks given card state as "disabled". It will not be possible to perform transactions using this card after the state change. This request has to include an initiated_by field, for which possible values are customer and merchant.{ "initiated_by": "customer" }
{ "id": "waupcxsbl6m2g", "customer": { "id": "wf1xucw3r6928" }, "created_at": 1583831680, "brand": "visa", "name": "John Smith", "num_bin": "444444", "num_last_4": "4448", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "91.17.133.219", "extra_data": {}, "straal_custom_data": {}, "state": "disabled", "state_flags": [ { "code": 1, "description": "Disabled by customer" } ] }
Payment Means
Payment mean is an object which represents a credit card associated with a digital wallet. Its ID acts as a token which can be used to perform further transactions.Payment Mean object attributes
Get a Payment Mean
Returns information of a specified payment mean associated with a digital wallet.{ "id": "k67jpi4ebv1vt", "customer": { "id": "tkje7gk28l7v8", "last_transaction": { "id": "kvj7atoezq8v1", "google_pay": { "id": "k67jpi4ebv1vt" }, "authentication_3ds": { "id": "7epprjhe1k5vt" } } }, "created_at": 1687856814, "type": "google_pay", "brand": "visa", "num_bin": "444444", "num_last_4": "4448", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "31.214.137.130" }
{ "id": "k67jpi4ebv1vt", "customer": { "id": "tkje7gk28l7v8", "last_transaction": { "id": "kvj7atoezq8v1", "google_pay": { "id": "k67jpi4ebv1vt" }, "authentication_3ds": { "id": "7epprjhe1k5vt" } } }, "created_at": 1687856814, "type": "google_pay", "brand": "visa", "num_bin": null, "num_last_4": null, "expiry_month": null, "expiry_year": null, "origin_ipaddr": "31.214.137.130" }
{ "id": "k67jpi4ebv1vt", "customer": { "id": "tkje7gk28l7v8", "last_transaction": { "id": "kvj7atoezq8v1", "apple_pay": { "id": "k67jpi4ebv1vt" }, "authentication_3ds": { "id": "7epprjhe1k5vt" } } }, "created_at": 1687856814, "type": "apple_pay", "brand": "mastercard", "num_bin": "444444", "num_last_4": "4448", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "31.214.137.130" }
{ "id": "k67jpi4ebv1vt", "customer": { "id": "tkje7gk28l7v8", "last_transaction": { "id": "kvj7atoezq8v1", "apple_pay": { "id": "k67jpi4ebv1vt" }, "authentication_3ds": { "id": "7epprjhe1k5vt" } } }, "created_at": 1687856814, "type": "apple_pay", "brand": "mastercard", "num_bin": null, "num_last_4": null, "expiry_month": null, "expiry_year": null, "origin_ipaddr": "31.214.137.130" }
Get customer's Payment Means
Returns a list of payment means assigned to a specified customer ID.GET /v1/customers/znhibktfny95i/cards?per_page=3&page=1
{ "page": 1, "per_page": 3, "total_count": 2, "data": [ { "id": "k67jpi4ebv1vt", "created_at": 1687856814, "type": "google_pay", "brand": "visa", "num_bin": "444444", "num_last_4": "4448", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "31.214.137.130" }, { "id": "w67jpi4ebv1vz", "created_at": 1687856814, "type": "apple_pay", "brand": "mastercard", "num_bin": "444444", "num_last_4": "4448", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "31.214.137.130" } ] }
Customers
Customer object represents your application/site user.Customer objects
Create a customer
{ "email": "[email protected]", "reference": "auIj01kcj98lfq", "external_reference": "dsa9d6ca9ds" }
{ "id": "mhtaqdb4edvrf", "created_at": 1467716585, "email": "[email protected]", "reference": "auIj01kcj98lfq", "external_reference": "dsa9d6ca9ds" }
Get a customer
Returns a customer for a specified ID.{ "id": "mhtaqdb4edvrf", "created_at": 1467716585, "email": "[email protected]", "reference": "auIj01kcj98lfq", "external_reference": "dsa9d6ca9ds", "order_reference": null, "last_transaction": { "id": "f9g63mazh1wi1" } }
Get the customer list
Returns a list of customers for the merchant's account.GET /v1/customers?per_page=2&page=1
{ "data": [ { "id": "5nffaefhmlc6h", "created_at": 1451655351, "email": "[email protected]", "reference": "81lau82pnneb8", "external_reference": "dsa9d6ca9ds", "order_reference": null, "last_transaction": { "id": "f9g63mazh1wi1" } }, { "id": "xdn0ffvrjxf6v", "created_at": 1467716585, "email": "[email protected]", "reference": "auIj01kcj98lfq", "external_reference": "dsa9d6ca9ds", "order_reference": null, "last_transaction": { "id": "f9g63mazh1wi1" } } ], "page": 1, "per_page": 2, "total_count": 3 }
Subscriptions
Subscription object allows you to automatically charge a user for a specified amount in a recurring manner. The amount depends on the plan associated with the subscription. Subscription requires a payment source, that is, a card or a bank account.Subscription object attributes
Allowed data types: timestamp or ISO formatted date ("YYYY-MM-DD")
Allowed data types: timestamp or ISO formatted date ("YYYY-MM-DD")
Available cancellation_source codes
Create a subscription
Creates a subscription for a specified card ID. You can use this method multiple times to create additional subscriptions for one card.{ "plan_id": "mcn15j2hwhq4f" }
{ "id": "m5lwrskt18r4f", "created_at": 1468577492, "active": true, "cancelled_at": null, "cancellation_source": null, "current_period_start": 1468577492, "current_period_end": 1471169492, "card": { "id": "mru196faf8r4f", "customer": { "id": "mj3mg7w3w8r4f" } }, "plan": { "id": "mcn15j2hwhq4f" }, "extra_data": {}, "transactions": [ { "amount": 100, "authorized": true, "pre_auth": false, "captured": false, "captures": [], "chargeback": null, "created_at": 1468577590, "currency": "usd", "decline_reason": null, "extra_data": {}, "id": "n4lar14f3a54f", "attempts": [], "with_3ds_params": false, "reference": null, "external_reference": null, "order_reference": null, "refunded": false, "refunds": [], "voided": false, "voids": [] } ], "straal_custom_data": {} }
Create a subscription with a card for a given customer
Creates a subscription for a specified customer ID. You can use this method multiple times to create additional subscriptions for one customer using different cards. The card created in this request automatically becomes active, which in practice means that all subscription transactions will be performed using this card.Notes:
- card object is required while sending a request to this URL
- when using this method, the credit card needs to be authorized, so Verification Authorization will be made. - created card object is added to response when an error occurs during subscription creation. You can use this object in other views.
{ "plan_id": "mcn15j2hwhq4f", "card": { "name": "Samwell Gordon", "number": "4444333322221111", "cvv": "789", "expiry_month": 7, "expiry_year": 2019, "origin_ipaddr": "54.4.125.235" } }
{ "id": "m5lwrskt18r4f", "created_at": 1468577492, "active": true, "cancelled_at": null, "cancellation_source": null, "current_period_start": 1468577492, "current_period_end": 1471169492, "card": { "id": "mru196faf8r4f", "created_at": 1468577403, "brand": "visa", "name": "Samwell Gordon", "num_bin": "444433", "num_last_4": "1111", "expiry_month": 7, "expiry_year": 2019, "origin_ipaddr": "54.4.125.235", "customer": { "id": "mj3mg7w3w8r4f" }, "state": "active", "state_flags": [], "extra_data": {}, "transactions": [ { "amount": 100, "authorized": true, "pre_auth": false, "captured": false, "captures": [], "chargeback": null, "created_at": 1468577590, "currency": "usd", "decline_reason": null, "extra_data": {}, "id": "n4lar14f3a54f", "attempts": [], "with_3ds_params": false, "reference": null, "external_reference": null, "order_reference": null, "refunded": false, "refunds": [], "voided": false, "voids": [] } ] }, "plan": { "id": "mcn15j2hwhq4f" }, "extra_data": {}, "straal_custom_data": {} }
{ "errors": [ { "message": "Authorization failed", "code": 60001 } ], "plan": { "id": "cwssdg3d951dt" }, "card": { "id": "mru196faf8r4f", "created_at": 1468577403, "brand": "visa", "name": "Samwell Gordon", "num_bin": "444433", "num_last_4": "1111", "expiry_month": 7, "expiry_year": 2019, "origin_ipaddr": "54.4.125.235", "customer": { "id": "mj3mg7w3w8r4f" }, "state": "active", "state_flags": [], "extra_data": {}, "transactions": [ { "amount": 100, "authorized": false, "captured": false, "captures": [], "chargeback": null, "created_at": 1468577590, "currency": "usd", "decline_reason": { "code": 1001, "description": "Declined by issuing bank" }, "extra_data": {}, "id": "n4lar14f3a54f", "attempts": [], "with_3ds_params": false, "reference": null, "external_reference": null, "order_reference": null, "refunded": false, "refunds": [], "voided": false, "voids": [] } ] }, "extra_data": {} }
Create a subscription with external MPI parameters
It's also possible to provide an optional 3D-Secure MPI data structure if the 3DS authentication has been performed by external MPI system. Optional mpi_params could be included in any of the following card transaction requests:Create a subscription
Create a subscription with a card for a given customer
Sample request for a $9.99 transaction with external 3DS params:
{ "plan_id":"mcn15j2hwhq4f", "card":{ "name":"Samwell Gordon", "number":"4444333322221111", "cvv":"789", "expiry_month":7, "expiry_year":2019, "origin_ipaddr":"54.4.125.235", "mpi_params":{ "cavv":"Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=", "ds_transaction_id":"231123123312", "eci":"05", "xid":"VEw4TkFrakFYMmEreXdoZE5xZUU=", "protocol_version":"2.1.0" } } }
{ "id":"m5lwrskt18r4f", "created_at":1468577492, "active":true, "cancelled_at":null, "cancellation_source":null, "current_period_start":1468577492, "current_period_end":1471169492, "card":{ "id":"mru196faf8r4f", "created_at":1468577403, "brand":"visa", "name":"Samwell Gordon", "num_bin":"444433", "num_last_4":"1111", "expiry_month":7, "expiry_year":2019, "origin_ipaddr":"54.4.125.235", "customer":{ "id":"mj3mg7w3w8r4f" }, "state":"active", "state_flags":[], "extra_data":{}, "transactions":[ { "amount":100, "authorized":true, "pre_auth":false, "captured":false, "captures":[], "chargeback":null, "created_at":1468577590, "currency":"usd", "decline_reason":null, "extra_data":{}, "id":"n4lar14f3a54f", "attempts":[], "with_3ds_params":true, "reference":null, "external_reference":null, "order_reference":null, "refunded":false, "refunds":[], "voided":false, "voids":[], "mpi_params":{ "cavv":"Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=", "ds_transaction_id":"231123123312", "eci":"05", "xid":"VEw4TkFrakFYMmEreXdoZE5xZUU=", "protocol_version":"2.1.0" } } ] }, "plan":{ "id":"mcn15j2hwhq4f" }, "extra_data":{}, "straal_custom_data":{} }
Create a subscription with optional 3DS challenge
Creates a subscription for a specified card ID with 3DS challenge possible. You can use this method multiple times to create additional subscriptions for one customer using different cards. If 3DS challenge will be required then subscription will become active after successful 3DS challenge. All subscription transactions will be performed using this card.Notes:
- when using this method, the credit card needs to be authorized, so Verification Authorization will be made.
{ "plan_id": "plan_id", "authentication_3ds": { "success_url": "http://example.com/success", "failure_url": "http://example.com/fail", "threeds_v2": { "browser": { "accept_header": "*/*", "color_depth": 24, "device_id": "", "ip": "213.120.141.140", "java_enabled": false, "javascript_enabled": false, "language": "pl-PL", "screen_height": 1080, "screen_width": 1920, "timezone": 0, "user_agent": "", "user_id": "" } } } }
{ "csr": { "id": "a1w9e3nqstkaw", "subscription": null, "transactions": [ { "id": "f9g63mazh1wi1" } ], "extra_data": {}, "straal_custom_data": {} }, "authentication_3ds": { "id": "a7lr1cpt2fzqk", "redirect_url": "https://checkout.straal.com/3ds_challenge" } }
{ "csr": { "id": "a1w9e3nqstkaw", "subscription": { "id": "a149e3nq89kaw" }, "transactions": [ { "id": "f9g63mazh1wi1" } ], "extra_data": {}, "straal_custom_data": {} }, "authentication_3ds": null }
{ "errors": [ { "message": "Authorization failed", "code": 60001 }, { "message": "3DS authentication failed", "code": 17015 } ], "csr": { "id": "a1w9e3nqstkaw", "subscription": "a149e3nq89kaw", "transactions": [ { "id": "f9g63mazh1wi1" } ], "extra_data": {}, "straal_custom_data": {} }, "authentication_3ds": null }
{ "errors": [ { "message": "Failed to decode JSON in HTTP request", "code": 95001 } ] }
Get a subscription
Returns details of an existing subscription.{ "id": "m5lwrskt18r4f", "created_at": 1468577492, "active": true, "cancelled_at": null, "cancellation_source": null, "current_period_start": 1468577492, "current_period_end": 1471169492, "card": { "id": "mru196faf8r4f", "customer": { "id": "mj3mg7w3w8r4f" } }, "plan": { "id": "mcn15j2hwhq4f" }, "extra_data": {}, "straal_custom_data": {} }
Get the subscription list
Returns a list of subscriptions for the merchant's account.GET /v1/subscriptions?per_page=2&page=1
{ "data": [ { "id": "m5lwrskt18r4f", "created_at": 1468577492, "active": true, "cancelled_at": null, "cancellation_source": null, "current_period_start": 1468577492, "current_period_end": 1471169492, "card": { "id": "mru196faf8r4f", "customer": { "id": "mj3mg7w3w8r4f" } }, "plan": { "id": "mcn15j2hwhq4f" }, "extra_data": {}, "straal_custom_data": {} }, { "id": "bo10e8kfc8pmc", "created_at": 1487258578, "active": true, "cancelled_at": null, "cancellation_source": null, "current_period_start": 1487258583, "current_period_end": 1489850578, "bank_account": { "id": "83ulegbkuvqmf", "customer": { "id": "q12l8eww2vymk" } }, "plan": { "id": "mcn15j2hwhq4f" }, "extra_data": {} } ], "page": 1, "per_page": 2, "total_count": 3 }
Get the subscription list for a given customer
Returns a list of subscriptions assigned to a specified customer ID.GET /v1/customers/:id/subscriptions?per_page=3&page=1
{ "data": [ { "id": "439to9r0ezfwq", "created_at": 1497258894, "active": true, "cancelled_at": null, "cancellation_source": null, "current_period_start": 1497950093, "current_period_end": 1500542093, "card": {"id": "ehgl79c6xm431"}, "plan": { "id": "v0fbvbm6m3fii" }, "extra_data": {}, "straal_custom_data": {} } ], "page": 1, "per_page": 3, "total_count": 1 }
Get the subscription list for a given card
Returns a list of subscriptions assigned to a specified card ID.GET /v1/cards/:id/subscriptions?per_page=3&page=1
{ "data": [ { "id": "r3jo8a6rga9t7", "created_at": 1497258894, "active": true, "cancelled_at": null, "cancellation_source": null, "current_period_start": 1497950093, "current_period_end": 1500542093, "plan": { "id": "amnbrf6htplmt" }, "extra_data": {}, "straal_custom_data": {} } ], "page": 1, "per_page": 3, "total_count": 1 }
Get subscribe status
Prepared especially for subscriptions created with optional 3DS Challange. Allows to get information about current state of subscription creation. Use this endpoint when you didn't receive redirect_url or you're not sure subscription has been created.Returns objects related with specific CSR.
{ "csr": { "id": "439to9r0ezfwq", "subscription": { "id": "jf7h46dbh75s2" }, "transactions": [ { "id": "834bhfr0eznsy" } ], "extra_data": {}, "straal_custom_data": {} }, "authentication_3ds": { "id": "84cjj3483d3fa", "redirect_url": "https://sample-redirect-url.com" } }
{ "csr": { "id": "439to9r0ezfwq", "subscription": null, "transactions": [ { "id": "834bhfr0eznsy" } ], "extra_data": {}, "straal_custom_data": {} }, "authentication_3ds": { "id": "84cjj3483d3fa", "redirect_url": "https://sample-redirect-url.com" } }
{ "csr": { "id": "439to9r0ezfwq", "subscription": null, "transactions": [ { "id": "834bhfr0eznsy" } ], "extra_data": {}, "straal_custom_data": {} }, "authentication_3ds": { "id": "84cjj3483d3fa", "redirect_url": null } }
{ "errors": [ { "code": 60001, "message": "Authorization failed" } ], "csr": { "id": "439to9r0ezfwq", "subscription": null, "transactions": [ { "id": "834bhfr0eznsy" } ], "extra_data": {}, "straal_custom_data": {} }, "authentication_3ds": { "id": "84cjj3483d3fa", "redirect_url": null } }
Cancel a subscription
Cancels an existing subscription. Use with caution: you cannot reinstate a cancelled subscription. You will have to create a new one instead.{ "id": "m5lwrskt18r4f", "created_at": 1468577492, "active": false, "cancelled_at": 1488214269, "cancellation_source": { "code": 1, "description": "API request" }, "current_period_start": 1468577492, "current_period_end": 1471169492, "card": { "id": "mru196faf8r4f", "customer": { "id": "mj3mg7w3w8r4f" } }, "plan": { "id": "mcn15j2hwhq4f" }, "extra_data": {}, "straal_custom_data": {} }
Plans
Plan defines how often and what amount will be taken off the customer's account during subscription lifetime.Plan object attributes
Create a plan
{ "name": "Regular monthly $19.99", "amount": 1999, "currency": "usd", "trial_days": 7, "step_type": "month", "step_value": 1 }
{ "id": "mj501ot7vxwsf", "created_at": 1470068395, "name": "Regular monthly $19.99", "amount": 1999, "currency": "usd", "trial_days": 7, "step_type": "month", "step_value": 1 }
Get a plan
Returns details of an existing plan.{ "id": "mj501ot7vxwsf", "created_at": 1470068395, "name": "Regular monthly $19.99", "amount": 1999, "currency": "usd", "trial_days": 7, "step_type": "month", "step_value": 1 }
Get the list of plans
Returns a list of plans for the merchant's account.GET /v1/plans?per_page=2&page=1
{ "data": [ { "id": "mj501ot7vxwsf", "created_at": 1470068395, "name": "Regular monthly $19.99", "amount": 1999, "currency": "usd", "trial_days": 7, "step_type": "month", "step_value": 1 }, { "id": "8o38exhmhtabr", "created_at": 1487591767, "name": "Premium monthly $59.99", "amount": 5999, "currency": "usd", "trial_days": 7, "step_type": "month", "step_value": 1 } ], "page": 1, "per_page": 2, "total_count": 3 }
Checkout Page
Checkout Page is a commonly used and popular choice for accepting payments online. This method will minimize the amount of work that has to be done to integrate with Straal.To initialize a new payment via the Checkout Page you have to initialize checkout page and redirect the user to the received checkout_url.
Straal will send notification to your backend about payment status - request_finished after a card transaction and pay_by_link_payment_succeeded or pay_by_link_payment_failed after pay-by-link payment.
In every notification, there is a checkout object nested inside the transaction object. You can match it to the checkout ID you received on checkout creation.
Checkout object attributes
Card transaction object attributes
Initialize checkout
{ "currency": "usd", "amount": 1999, "ttl": 600, "return_url": "https://yourproduct.com/payment_succeed.html", "failure_url": "https://yourproduct.com/payment_failed.html", "lang": "en", "order_description": "Star Wars mug XXL", "order_reference": "26906303414c4f2782c653e0501c13b1", "card_transaction": { "type": "oneclick" }, "extra_data": { "some": "additional_data" } }
{ "id": "a9szcp9u9e8n3", "created_at": 1519841724, "amount": 1999, "currency": "usd", "ttl": 600, "attempts": [], "checkout_url": "https://checkout.straal.com/en/9ad38808ebbc7be00e74b86bc28542", "return_url": "https://yourproduct.com/payment_succeed.html", "failure_url": "https://yourproduct.com/payment_failed.html", "order_description": "Star Wars mug XXL", "order_reference": "26906303414c4f2782c653e0501c13b1", "extra_data": { "some": "additional_data" } }
Get checkout object
{ "id": "a9szcp9u9e8n3", "created_at": 1519841724, "amount": 1999, "currency": "usd", "ttl": 600, "checkout_url": "https://checkout.straal.com/9ad38808ebbc7be00e74b86bc28542", "return_url": "https://yourproduct.com/payment_succeed.html", "failure_url": "https://yourproduct.com/payment_failed.html", "order_description": "Star Wars mug XXL", "order_reference": "26906303414c4f2782c653e0501c13b1", "af_profiling_reference": "01H3C352WP56M8ZZ2R41B4FG48", "af_user_reference": null, "merchant_image": null, "use_3ds": true, "extra_data": { "some": "additional_data" }, "customer": { "id": "qv9dpoblsbunc", "last_transaction": { "id": "u25mpvzysb9nm", "card": { "id": "ydpjpudy6bsn5" }, "authentication_3ds": { "id": "xj74j6bhosjr6" } } }, "attempts": [ { "id": "ygydpuy77bsnv", "created_at": 1519841764, "status": "succeeded", "session_reference": "9a7ba125cb5f4956b4c2d714c50cad3e", "profiler_url": null, "transaction": { "id": "u25mpvzysb9nm", "attempts": [], "with_3ds_params": true, "created_at": 1519841765, "reference": null, "external_reference": null, "order_reference": "26906303414c4f2782c653e0501c13b1", "amount": 1999, "currency": "usd", "method": "card", "decline_reason": null, "authorized": true, "pre_auth": false, "captured": true, "authentication_3ds": { "id": "xj74j6bhosjr6", "created_at": 1687259038, "success_url": "http://127.0.0.1:25001/success", "failure_url": "http://127.0.0.1:25001/failure", "enrollment_status": "Y", "errors": [], "status": "succeeded", "eci": "05", "protocol_version": "2.1.0", "threeds_flow": "frictionless", "threeds_v2": { "browser": { "ip": "94.113.114.115", "language": "en-GB", "timezone": -120, "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36", "color_depth": 24, "java_enabled": false, "screen_width": 1920, "accept_header": "*/*", "screen_height": 1080, "javascript_enabled": true } } }, "captures": [ { "id": "52jcsp07sbpnu", "status": "succeeded", "created_at": 1519841768, "amount": 1999, "extra_data": {} } ], "card": { "id": "ydpjpudy6bsn5", "created_at": 1519841765, "state": "active", "state_flags": [], "name": "Harry Potter", "num_bin": "444444", "num_last_4": "4448", "expiry_month": 10, "expiry_year": 2021, "brand": "visa", "origin_ipaddr": "94.113.114.115", "extra_data": {}, "straal_custom_data": {} }, "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "extra_data": {}, "straal_custom_data": {} }, "authentication_3ds": { "id": "xj74j6bhosjr6", "card": { "id": "ydpjpudy6bsn5", "customer": { "id": "qv9dpoblsbunc", "last_transaction": { "id": "u25mpvzysb9nm", "authentication_3ds": { "id": "xj74j6bhosjr6" } } } }, "subscription": null, "token_3ds": { "id": "xhjui7x2iscr6" } } } ] }
{ "id": "a9szcp9u9e8n3", "created_at": 1519841724, "amount": 1999, "currency": "usd", "ttl": 600, "checkout_url": "https://checkout.straal.com/9ad38808ebbc7be00e74b86bc28542", "return_url": "https://yourproduct.com/payment_succeed.html", "failure_url": "https://yourproduct.com/payment_failed.html", "order_description": "Star Wars mug XXL", "order_reference": "26906303414c4f2782c653e0501c13b1", "af_profiling_reference": "01H3C352WP56M8ZZ2R41B4FG48", "af_user_reference": null, "merchant_image": null, "use_3ds": true, "extra_data": { "some": "additional_data" }, "customer": { "id": "qv9dpoblsbunc", "last_transaction": { "id": "u25mpvzysb9nm", "google_pay": { "id": "ydpjpudy6bsn5" }, "authentication_3ds": { "id": "xj74j6bhosjr6" } } }, "attempts": [ { "id": "ygydpuy77bsnv", "created_at": 1519841764, "status": "succeeded", "session_reference": "9a7ba125cb5f4956b4c2d714c50cad3e", "profiler_url": null, "transaction": { "id": "u25mpvzysb9nm", "attempts": [], "with_3ds_params": true, "created_at": 1519841765, "reference": null, "external_reference": null, "order_reference": "26906303414c4f2782c653e0501c13b1", "amount": 1999, "currency": "usd", "method": "card", "decline_reason": null, "authorized": true, "pre_auth": false, "captured": true, "authentication_3ds": { "id": "xj74j6bhosjr6", "created_at": 1687259038, "success_url": "http://127.0.0.1:25001/success", "failure_url": "http://127.0.0.1:25001/failure", "enrollment_status": "Y", "errors": [], "status": "succeeded", "eci": "05", "protocol_version": "2.1.0", "threeds_flow": "frictionless", "threeds_v2": { "browser": { "ip": "94.113.114.115", "language": "en-GB", "timezone": -120, "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36", "color_depth": 24, "java_enabled": false, "screen_width": 1920, "accept_header": "*/*", "screen_height": 1080, "javascript_enabled": true } } }, "captures": [ { "id": "52jcsp07sbpnu", "status": "succeeded", "created_at": 1519841768, "amount": 1999, "extra_data": {} } ], "google_pay": { "id": "ydpjpudy6bsn5", "created_at": 1689151754, "type": "google_pay", "brand": "visa", "num_bin": "444444", "num_last_4": "4448", "expiry_month": 11, "expiry_year": 23, "origin_ipaddr": "31.214.137.130" }, "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "extra_data": {}, "straal_custom_data": {} }, "authentication_3ds": { "id": "xj74j6bhosjr6", "google_pay": { "id": "ydpjpudy6bsn5" }, "subscription": null, "token_3ds": { "id": "xhjui7x2iscr6" } } } ] }
{ "id": "a9szcp9u9e8n3", "created_at": 1519841724, "amount": 1999, "currency": "usd", "ttl": 600, "checkout_url": "https://checkout.straal.com/9ad38808ebbc7be00e74b86bc28542", "return_url": "https://yourproduct.com/payment_succeed.html", "failure_url": "https://yourproduct.com/payment_failed.html", "order_description": "Star Wars mug XXL", "order_reference": "26906303414c4f2782c653e0501c13b1", "af_profiling_reference": "01H3C352WP56M8ZZ2R41B4FG48", "af_user_reference": null, "merchant_image": null, "use_3ds": true, "extra_data": { "some": "additional_data" }, "customer": { "id": "qv9dpoblsbunc", "last_transaction": { "id": "u25mpvzysb9nm", "apple_pay": { "id": "ydpjpudy6bsn5" }, "authentication_3ds": { "id": "xj74j6bhosjr6" } } }, "attempts": [ { "id": "ygydpuy77bsnv", "created_at": 1519841764, "status": "succeeded", "session_reference": "9a7ba125cb5f4956b4c2d714c50cad3e", "profiler_url": null, "transaction": { "id": "u25mpvzysb9nm", "attempts": [], "with_3ds_params": true, "created_at": 1519841765, "reference": null, "external_reference": null, "order_reference": "26906303414c4f2782c653e0501c13b1", "amount": 1999, "currency": "usd", "method": "card", "decline_reason": null, "authorized": true, "pre_auth": false, "captured": true, "authentication_3ds": { "id": "xj74j6bhosjr6", "created_at": 1687259038, "success_url": "http://127.0.0.1:25001/success", "failure_url": "http://127.0.0.1:25001/failure", "enrollment_status": "Y", "errors": [], "status": "succeeded", "eci": "05", "protocol_version": "2.1.0", "threeds_flow": "frictionless", "threeds_v2": { "browser": { "ip": "94.113.114.115", "language": "en-GB", "timezone": -120, "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36", "color_depth": 24, "java_enabled": false, "screen_width": 1920, "accept_header": "*/*", "screen_height": 1080, "javascript_enabled": true } } }, "captures": [ { "id": "52jcsp07sbpnu", "status": "succeeded", "created_at": 1519841768, "amount": 1999, "extra_data": {} } ], "apple_pay": { "id": "ydpjpudy6bsn5", "created_at": 1689151754, "type": "apple_pay", "brand": "visa", "num_bin": "444444", "num_last_4": "4448", "expiry_month": 11, "expiry_year": 23, "origin_ipaddr": "31.214.137.130" }, "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "extra_data": {}, "straal_custom_data": {} }, "authentication_3ds": { "id": "xj74j6bhosjr6", "apple_pay": { "id": "ydpjpudy6bsn5" }, "subscription": null, "token_3ds": { "id": "xhjui7x2iscr6" } } } ] }
CryptKeys
CryptKey is a special object that allows you to send encrypted data directly to our API endpoint without needing to authorize using API Key. This can be useful in various scenarios, such as making a request from mobile or web applications where you can't expose the API Key. CryptKey can be used to make only a single request and can be generated only with one permission which reflects specific API requests. Because the data is not sent through your back end, you have to keep in mind fewer PCI-compliance requirements.CryptKey object attributes
Create a CryptKey
A request for creating CryptKey has to be authorized by an API Key. It means that you have to make it from your application backend.{ "permission": "v1.cards.create", "customer_id": "mzivhql5yi9rf" }
{ "id": "70xfzmynzgkih", "created_at": 1470302857, "key": "06c5fbc1a9800003ba(...)", "af_attempt_reference": "01TGR3VANKBBAQRCJNMRA1T2R9", "permission": "v1.cards.create", "ttl": 600 }
Usage
Every request encrypted with CryptKey should be sent to special endpoint:- Create a transaction with a card using CryptKey
- Create a card using CryptKey
- Initialize a 3D-Secure authentication process using CryptKey
CSRs (Create Subscription Requests)
Create Subscription Request object stores data related to subscription creation: card or bank account, transactions, plan and, if the request succeeded, also subscription. We create CSR objects automatically for correctly formed POST requests to subscription endpoints.CSR object attributes
Get a CSR
Returns details of a CSR.{ "antifraud_response": { "advice": "accept" }, "bank_account": null, "card": { "customer": { "id": "ear228iqwtkaa" }, "id": "khaete0qbtwav" }, "created_at": 1492785759, "errors": [], "id": "a1w9e3nqstkaw", "plan": { "id": "an7der6qztkaw" }, "subscription": { "id": "kllcsanqwteat", "plan": { "id": "an7der6qztkaw" } }, "transactions": [ { "captures": [ { "id": "wlciak9q5tear" } ], "id": "kzfmtaoqwteak", "attempts": [], "with_3ds_params": false, "refunds": [ { "id": "ltqat1ecykkaw" } ], "voids": [] } ] }
Get the CSR list
Returns the list of CSRs for the merchant's account.GET /v1/csrs?per_page=2&page=1
{ "data": [ { "antifraud_response": { "advice": "accept" }, "bank_account": null, "card": { "customer": { "id": "ear228iqwtkaa" }, "id": "khaete0qbtwav" }, "created_at": 1492785759, "errors": [], "id": "a1w9e3nqstkaw", "plan": { "id": "an7der6qztkaw" }, "subscription": { "id": "kllcsanqwteat", "plan": { "id": "an7der6qztkaw" } }, "transactions": [ { "captures": [ { "id": "wlciak9q5tear" } ], "id": "kzfmtaoqwteak", "attempts": [], "with_3ds_params": false, "refunds": [ { "id": "ltqat1ecykkaw" } ], "voids": [] } ] }, { "antifraud_response": { "advice": "refuse" }, "bank_account": null, "card": { "customer": { "id": "qfdafg43sdfgh" }, "id": "bvzxadfjk34df" }, "created_at": 1492784444, "errors": [ {"code": 70001, "message": "Dropped by antifraud"} ], "id": "a345fghjsvsa", "plan": { "id": "vcxea35tsdfa" }, "subscription": null, "transactions": [] } ], "page": 1, "per_page": 2, "total_count": 2 }
APM payments
An Alternative Payment Method (APM) object represents an APM payment attempt made by a customer.APM payment object attributes
Initialize an APM payment
This method allows you to initialize an APM payment for a previously created customer object.{ "currency": "eur", "amount": 50, "return_url": "https://yourproduct.com/payment_succeeded", "failure_url": "https://yourproduct.com/payment_failed", "description": "Order 1234", "reference": "qwerty1234", "origin_ipaddr": "123.123.123.123", "payment_method_ident": "skrill", "external_reference": "ABC123123ABC", "billing_details": { "street": "100 Queen", "city": "Toronto", "zip": "M5H 2N2", "country": "CA" }, "merchant_descriptor": { "dynamic_descriptor": "OnlineStore", "phone": "12345678" } }
{ "id": "glko5j5mfurc1", "customer": { "id": "564rjzue9npc8", "last_transaction": { "id": "ukuj5mkmkrgc1" } }, "created_at": 1700741239, "amount": 50, "currency": "eur", "redirect_url": "https://apm-authentication-page.com", "return_url": "https://yourproduct.com/payment_succeeded", "failure_url": "https://yourproduct.com/payment_failed", "description": "Order 1234", "reference": "qwerty1234", "origin_ipaddr": "123.123.123.123", "payment_method_ident": "skrill", "external_reference": "ABC123123ABC", "status": "new" }
Pay-by-link payments
A pay-by-link payment object represents a pay-by-link payment attempt made by a customer.Pay-by-link payment object attributes
[DEPRECATED] Initialize a Pay-by-link payment
Deprecated in favor of generic APM.This method allows you to initialize a pay-by-link payment for a previously created customer object.
{ "currency": "pln", "amount": 1499, "return_url": "https://yourproduct.com/payment_succeeded", "failure_url": "https://yourproduct.com/payment_failed", "description": "Order 123123", "reference": "qwerty1234qwerty", "order_reference": null, "origin_ipaddr": "123.123.123.123", "payment_method_ident": "bank1" }
{ "id": "fjdan27fk72na", "created_at": 1472491810, "redirect_url": "https://bank1.example.com", "currency": "pln", "amount": 1499, "return_url": "https://yourproduct.com/payment_succeeded", "failure_url": "https://yourproduct.com/payment_failed", "description": "Order 123123", "reference": "qwerty1234qwerty", "order_reference": null, "origin_ipaddr": "123.123.123.123", "payment_method_ident": "bank1", "external_reference": "ABC123123ABC", "status": "pending" }
Payment methods
Payment method is an object that represents methods that can be used to make an APM payment or a Pay-by-link payment.Payment method object attributes
Get the list of payment methods
Returns a list of available payment methods. Using information obtained from that endpoint you can render payment method selection view to the end user.[ { "description": "Pay with Straal", "ident": "card", "image_url": "https://static.straal.com/straal_logo_pbl.png", "meta": {}, "status": "enabled", "supported_currencies": ["USD", "BRL", "EUR", "PLN"], "type": "card" }, { "description": "Success", "ident": "integration_success", "image_url": "https://static.straal.com/integration_success.png", "meta": {}, "status": "enabled", "supported_currencies": ["PLN"], "type": "bank_transfer" }, { "description": "Failure", "ident": "integration_failure", "image_url": "https://static.straal.com/integration_failure.png", "meta": {}, "status": "enabled", "supported_currencies": ["PLN"], "type": "bank_transfer" }, { "description": "Temporarily disabled", "ident": "integration_temporarily_disabled", "image_url": "https://static.straal.com/integration_temporarily_disabled.png", "meta": {}, "status": "temporary_disabled", "supported_currencies": ["PLN"], "type": "bank_transfer" }, { "description": "Pay with Skrill", "ident": "skrill", "image_url": "https://static.straal.com/skrill.png", "meta": {}, "status": "enabled", "supported_currencies": ["EUR"], "type": "apm" }, { "description": "Pay with Neteller", "ident": "neteller", "image_url": "", "image_url": "https://static.straal.com/neteller.png", "status": "enabled", "supported_currencies": ["EUR", "PLN"], "type": "apm" }, { "description": "Pay with Blik", "ident": "blik", "image_url": "https://static.straal.com/blik.png", "meta": {}, "status": "enabled", "supported_currencies": ["PLN"], "type": "apm" } ]
Voids
The void object represents a void operation performed on a previously authorised transaction. You can void transactions that were successfully authorized and haven't been voided yet.Void object attributes
Create a void
This method allows you to perform a void on a previously authorised transaction. The void method returns the transaction object for which the void has been attempted. If the void succeeded, the voided attribute on the transaction object is set to true.{ "extra_data": { "custom_field": "value" } }
{ "id": "r33crz06i0gf5", "attempts": [], "with_3ds_params": false, "created_at": 1539177769, "amount": 1000, "currency": "usd", "authorized": true, "pre_auth": false, "captured": false, "captures": [], "refunded": false, "refunds": [], "voided": true, "voids": [ { "id": "54cr3kendrgfd", "created_at": 1539177769, "status": "succeeded", "extra_data": {} } ], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "decline_reason": null, "extra_data": {} }
Credits [BETA]
Credits (also known as OCTs, short for Original Credit Transfers) enable you to perform transfers from your merchant account to a previously debited customer's card.This method is useful for paying out winnings, salaries and other scenarios where you need to transfer money to your users.
Credit object represents a credit transaction performed using our API. To perform a credit you will need to reference a previous successful (captured) transaction.
Credit object attributes
Issue a credit
This method allows you to perform a credit referencing a previously performed card transaction.The transaction referenced by the credit operation must be a card transaction (and not e.g. SEPA), and must have been successfully authorized.
{ "amount": 999, "reference": "b138bc50148440ee", "description": "Winnings from 2021-05" }
{ "id": "jw4cl5030rwrh", "original_transaction": { "id": "csj6ply30hwrj", "card": { "id": "jpe5jc130h6rw", "customer": { "id": "ca9ae1u30hwrj", "last_transaction": { "id": "csj6ply30hwrj" } } } }, "created_at": 1593417828, "amount": 999, "currency": "eur", "description": "Winnings from 2021-05", "reference": "b138bc50148440ee", "extra_data": {}, "status": "succeeded", "errors": [] }
Get details about specific credit
{ "id": "xkjh2wc02asr9", "original_transaction": { "id": "98mjmc70xnjra", "card": { "id": "9cj2ct706abrx", "customer": { "id": "94caj820naxrm", "last_transaction": { "id": "98mjmc70xnjra" } } } }, "created_at": 1593424054, "amount": 999, "currency": "eur", "description": "Winnings from 2021-05", "reference": "b138bc50148440ee", "extra_data": {}, "status": "succeeded", "errors": [] }
Get a list of credits
Returns a list of credits for the merchant's account.GET /v1/credits?per_page=2&page=1
{ "data": [ { "id": "xkjh2wc02asr9", "original_transaction": { "id": "98mjmc70xnjra", "card": { "id": "9cj2ct706abrx", "customer": { "id": "94caj820naxrm", "last_transaction": { "id": "98mjmc70xnjra" } } } }, "created_at": 1593424054, "amount": 999, "currency": "eur", "description": "Winnings from 2021-05", "reference": "b138bc50148440ee", "extra_data": {}, "status": "succeeded", "errors": [] }, { "id": "xscp9jvm8adrl", "original_transaction": { "id": "98mjmc70xnjra", "card": { "id": "9cj2ct706abrx", "customer": { "id": "94caj820naxrm", "last_transaction": { "id": "98mjmc70xnjra" } } } }, "created_at": 1593424054, "amount": 1024, "currency": "eur", "description": "Winnings from 2021-06", "reference": "b138bc50148440ef", "extra_data": {}, "status": "failed", "errors": [] } ], "page": 1, "per_page": 2, "total_count": 2 }
Get a list of credits based on a selected transaction
Returns a list of credits referencing a specified transaction ID.GET /v1/transactions/98mjmc70xnjra/credits?per_page=2&page=1
{ "data": [ { "id": "xkjh2wc02asr9", "original_transaction": { "id": "98mjmc70xnjra", "card": { "id": "9cj2ct706abrx", "customer": { "id": "94caj820naxrm", "last_transaction": { "id": "98mjmc70xnjra" } } } }, "created_at": 1593424054, "amount": 999, "currency": "eur", "description": "Winnings from 2021-05", "reference": "b138bc50148440ee", "extra_data": {}, "status": "succeeded", "errors": [] }, { "id": "xscp9jvm8adrl", "original_transaction": { "id": "98mjmc70xnjra", "card": { "id": "9cj2ct706abrx", "customer": { "id": "94caj820naxrm", "last_transaction": { "id": "98mjmc70xnjra" } } } }, "created_at": 1593424054, "amount": 1024, "currency": "eur", "description": "Winnings from 2021-06", "reference": "b138bc50148440ef", "extra_data": {}, "status": "failed", "errors": [] } ], "page": 1, "per_page": 2, "total_count": 2 }
Get customer's credits
Returns a list of credits for a specified customer ID.GET /v1/customers/94caj820naxrm/credits?per_page=2&page=1
{ "data": [ { "id": "xkjh2wc02asr9", "original_transaction": { "id": "98mjmc70xnjra", "card": { "id": "9cj2ct706abrx", "customer": { "id": "94caj820naxrm", "last_transaction": { "id": "98mjmc70xnjra" } } } }, "created_at": 1593424054, "amount": 999, "currency": "eur", "description": "Winnings from 2021-05", "reference": "b138bc50148440ee", "extra_data": {}, "status": "succeeded", "errors": [] }, { "id": "xscp9jvm8adrl", "original_transaction": { "id": "98mjmc70xnjra", "card": { "id": "9cj2ct706abrx", "customer": { "id": "94caj820naxrm", "last_transaction": { "id": "98mjmc70xnjra" } } } }, "created_at": 1593424054, "amount": 1024, "currency": "eur", "description": "Winnings from 2021-06", "reference": "b138bc50148440ef", "extra_data": {}, "status": "failed", "errors": [] } ], "page": 1, "per_page": 2, "total_count": 2 }
Straal Direct payments
A Straal Direct payment object represents a Straal Direct payment attempt made by a customer.Straal Direct payment object attributes
Keep in mind
- Initialized payment is valid for 20 minutes. After that time the payment link expires.
Start a Straal Direct payment initiation process
This method allows you to start a Straal Direct payment initiation process for a previously created customer object.{ "currency": "eur", "amount": 1499, "return_url": "https://yourproduct.com/payment_initiated", "description": "Order 123123", "reference": "b13sadkauasdmn", "order_reference": "MyRef123", "origin_ipaddr": "123.123.123.123", "customer_name": "Jan Kowalski", "merchant_account_number": "123456789098765", "institution_id": "16ae7f18-782b-4c64-8e50-da963c9831ed" }
{ "id": "b138bc50148440ee", "created_at": 1472491810, "redirect_url": "https://checkout.straal.com/straal_direct_payment_init/some_token", "reference": "b13sadkauasdmn", "external_reference": "AJASND-SFLSDJH", "currency": "eur", "amount": 1499, "return_url": "https://yourproduct.com/payment_initiated", "description": "Order 123123", "order_reference": "MyRef123", "origin_ipaddr": "123.123.123.123", "status": "pending", "customer": { "id": "cebculc21t6ku", "last_transaction": { "id": "u0j6kuvwrkcku" } }, "transaction": { "id": "u0j6kuvwrkcku" } }
Deprecated resources
These API methods are deprecated and should not be used in new integrations.Create a transaction with a card and a customer
This method allows you to perform a transaction, create a card and a customer in one request.{ "amount": 999, "currency": "usd", "reference": "b138bc50148440ee", "order_reference": null, "card": { "name": "John Smith", "number": "4444444444444448", "cvv": "123", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "91.17.133.219", "customer": { "email": "[email protected]", "reference": "auIj01kcj98lfq", "external_reference": "dsa9d6ca9ds" } } }
{ "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "usd", "method": "card", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "qkymdfy2jbui1", "created_at": 1470239156, "amount": 999 } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "mzivhql5yi9rf", "created_at": 1467906605, "brand": "visa", "name": "John Smith", "num_bin": "444444", "num_last_4": "4448", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "91.17.133.219", "state": "active", "state_flags": [], "customer": { "id": "mhtaqdb4edvrf", "created_at": 1467716585, "email": "[email protected]", "reference": "auIj01kcj98lfq", "external_reference": "dsa9d6ca9ds" } }, "decline_reason": null, "extra_data": {} }
Create a card with a customer
{ "name": "John Smith", "number": "4444444444444448", "cvv": "123", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "91.17.133.219", "customer": { "email": "[email protected]", "reference": "auIj01kcj98lfq", "external_reference": "dsa9d6ca9ds" } }
{ "id": "mzivhql5yi9rf", "created_at": 1467906605, "state": "active", "state_flags": [], "brand": "visa", "name": "John Smith", "num_bin": "444444", "num_last_4": "4448", "expiry_month": 11, "expiry_year": 2023, "origin_ipaddr": "91.17.133.219", "customer": { "id": "mhtaqdb4edvrf", "created_at": 1467716585, "email": "[email protected]", "reference": "auIj01kcj98lfq", "external_reference": "dsa9d6ca9ds" } }
Create a subscription with a card and a customer
This method allows creating a subscription and a customer using a single request by sending both required objects (card and customer). The card created in this request automatically becomes active, which in practice means that all subscription transactions will be performed using this card.Notes:
- card and customer objects are required while sending a request to this URL
- when using this method, the credit card needs to be authorized, so Verification Authorization will be made.
- created card and customer objects are added to response when an error occurs during subscription creation. You can use these objects in other views.
{ "plan_id": "mcn15j2hwhq4f", "card": { "name": "Samwell Gordon", "number": "4444333322221111", "cvv": "789", "expiry_month": 7, "expiry_year": 2019, "origin_ipaddr": "54.4.125.235", "customer": { "email": "[email protected]", "reference": 7459320801, "external_reference": "dsa9d6ca9ds" } } }
{ "id": "m5lwrskt18r4f", "created_at": 1468577492, "active": true, "cancelled_at": null, "cancellation_source": null, "current_period_start": 1468577492, "current_period_end": 1471169492, "card": { "id": "mru196faf8r4f", "created_at": 1468577403, "brand": "visa", "name": "Samwell Gordon", "num_bin": "444433", "num_last_4": "1111", "expiry_month": 7, "expiry_year": 2019, "origin_ipaddr": "54.4.125.235", "customer": { "id": "mj3mg7w3w8r4f", "created_at": 1468577694, "email": "[email protected]", "reference": "7459320801", "external_reference": "dsa9d6ca9ds" }, "state": "active", "state_flags": [], "extra_data": {}, "transactions": [ { "amount": 100, "authorized": true, "pre_auth": false, "captured": false, "captures": [], "chargeback": null, "created_at": 1468577590, "currency": "usd", "decline_reason": null, "extra_data": {}, "id": "n4lar14f3a54f", "attempts": [], "with_3ds_params": false, "reference": null, "external_reference": null, "order_reference": null, "refunded": false, "refunds": [], "voided": false, "voids": [] } ] }, "plan": { "id": "mcn15j2hwhq4f" }, "extra_data": {}, "straal_custom_data": {} }
{ "errors": [ { "message": "Authorization failed", "code": 60001 } ], "plan": { "id": "cwssdg3d951dt" }, "card": { "id": "mru196faf8r4f", "created_at": 1468577403, "brand": "visa", "name": "Samwell Gordon", "num_bin": "444433", "num_last_4": "1111", "expiry_month": 7, "expiry_year": 2019, "origin_ipaddr": "54.4.125.235", "customer": { "id": "mj3mg7w3w8r4f", "created_at": 1522238802, "email": "[email protected]", "reference": "7459320801", "external_reference": "dsa9d6ca9ds" }, "state": "active", "state_flags": [], "extra_data": {}, "transactions": [ { "amount": 100, "authorized": false, "captured": false, "captures": [], "chargeback": null, "created_at": 1468577590, "currency": "usd", "decline_reason": { "code": 1001, "description": "Declined by issuing bank" }, "extra_data": {}, "id": "n4lar14f3a54f", "attempts": [], "with_3ds_params": false, "reference": null, "external_reference": null, "order_reference": null, "refunded": false, "refunds": [], "voided": false, "voids": [] } ] }, "extra_data": {} }
Straal.js
Overview
Straal.js is a helper library to make it easier to make API requests directly from the merchant's website. It utilizes client-side encryption and sends data over HTTPS to perform secure transactions.Download
You can download Straal.js from Straal GitHubUsage
In order to perform a transaction request directly from your website you have to do the following:1. Create a CryptKey on your application backend.
2. Pass the generated CryptKey to the frontend part of your site (via request or templating).
3. Pass CryptKey into Straal.js client code.
Notifications
Overview
Straal can notify your backend about certain events. For example, when we charge customer subscription, or after a transaction performed by your user from a mobile device. The notification is a regular HTTP request with JSON-formatted data.Request finished
Event name: request_finishedIf you are using Straal Checkout Page, we strongly recommend you handle the Checkout attempt finished notification instead.
When configured, this notification is sent each time when a transaction-related request is made. It contains the entire response body along with some extra information. Configuring this notification is highly recommended for clients sending encrypted requests directly from their website or a mobile device.
You can filter out the most relevant notifications by by checking the permission field in the data object.
Sample notification for card transaction:
{ "event": "request_finished", "data": { "path": "/v1/cards/mzivhql5yi9rf/transactions", "permission": "v1.transactions.create", "auth_method": "cryptkey", "cryptkey": { "id": "70xfzmynzgkih" }, "request_id": "0e04ead77926441c9369f1932ddd13c8", "response": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "usd", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "qkymdfy2jbui1", "created_at": 1470239156, "amount": 999 } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "decline_reason": null, "extra_data": {} } } }
{ "type": "predefined", "endpoint": "default", "request_data": { "event": "request_finished", "data": { "path": "/v1/cards/mzivhql5yi9rf/transactions", "permission": "v1.transactions.create", "auth_method": "apikey", "cryptkey": { "id": "70xfzmynzgkih" }, "request_id": "0e04ead77926441c9369f1932ddd13c8", "http_status_code": 200, "response": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "usd", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "qkymdfy2jbui1", "created_at": 1470238921, "amount": 999, "status": "succeeded", "extra_data": {} } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": "711000000024547624", "order_reference": null, "method": "google_pay", "google_pay": { "id": "mzivhql5yi9rf", "customer": { "id": "7fz9j6evnsgtc", "last_transaction": { "id": "gkjae74suiutt" } } }, "decline_reason": null, "extra_data": {} } } } }
{ "type": "predefined", "endpoint": "default", "request_data": { "event": "request_finished", "data": { "path": "/v1/cards/mzivhql5yi9rf/transactions", "permission": "v1.transactions.create", "auth_method": "apikey", "cryptkey": { "id": "70xfzmynzgkih" }, "request_id": "0e04ead77926441c9369f1932ddd13c8", "http_status_code": 200, "response": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "usd", "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "qkymdfy2jbui1", "created_at": 1470238921, "amount": 999, "status": "succeeded", "extra_data": {} } ], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": "711000000024547624", "order_reference": null, "method": "apple_pay", "apple_pay": { "id": "mzivhql5yi9rf", "customer": { "id": "7fz9j6evnsgtc", "last_transaction": { "id": "gkjae74suiutt" } } }, "decline_reason": null, "extra_data": {} } } } }
Checkout Page
These notifications are sent only for transactions made via Straal Checkout Page.Checkout attempt finished
Event name: checkout_attempt_finishedThis notification is sent when a single payment attempt via Straal Checkout Page is finished.
Sample notification for card transaction:
{ "event": "checkout_attempt_finished", "data": { "checkout": { "id": "iqxjxcr01hcko", "af_profiling_reference": null, "af_user_reference": null, "amount": 1000, "checkout_url": "https://checkout.straal.com/f4k3", "created_at": 1554385200, "currency": "pln", "customer": { "id": "c0cxh9x04xikh" }, "extra_data": {}, "failure_url": "https://yourproduct.com/payment_failed", "merchant_image": null, "order_description": null, "order_reference": "some_order_reference", "return_url": "https://yourproduct.com/payment_succeeded", "ttl": 600, "use_3ds": true }, "checkout_attempt": { "id": "hj9cxs20d0cki", "af_attempt_reference": null, "authentication_3ds": { "id": "dfa234gatkgh5", "card": { "id": "xupuuc40ihukc", "customer": { "id": "c0cxh9x04xikh" } } }, "created_at": 1554385200, "profiler_url": "https://profiler.com/some_profiling_script.js", "session_reference": "778779f3ba974afbab8b7133b6094f96", "status": "succeeded" }, "transaction": { "id": "cxjepxt0ihck2", "amount": 1000, "attempts": [], "with_3ds_params": true, "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "e5iraxm0ajckq", "amount": 1000, "status": "succeeded", "created_at": 1554385200, "extra_data": {} } ], "card": { "id": "xupuuc40ihukc", "customer": { "id": "c0cxh9x04xikh", "last_transaction": { "id": "cxjepxt0ihck2" } } }, "chargeback": null, "created_at": 1554385200, "currency": "pln", "decline_reason": null, "method": "card", "reference": "some_order_reference", "external_reference": null, "refunded": false, "voided": false, "extra_data": {} } } }
{ "event": "checkout_attempt_finished", "data": { "checkout": { "id": "iqxjxcr01hcko", "af_profiling_reference": null, "af_user_reference": null, "amount": 1000, "checkout_url": "https://checkout.straal.com/f4k3", "created_at": 1554385200, "currency": "pln", "customer": { "id": "c0cxh9x04xikh", "last_transaction": { "id": "cxjepxt0ihck2", "authentication_3ds": { "id": "cxjepxt0ihck2" } } }, "extra_data": {}, "failure_url": "https://yourproduct.com/payment_failed", "merchant_image": null, "order_description": "Product F8DCFE77", "order_reference": "f8dcfe778c9749cfbe7ea50fc826f202", "return_url": "https://yourproduct.com/payment_succeeded", "ttl": 600, "use_3ds": true }, "checkout_attempt": { "id": "hj9cxs20d0cki", "authentication_3ds": { "id": "dfa234gatkgh5", "card": null }, "created_at": 1554385200, "profiler_url": null, "session_reference": "778779f3ba974afbab8b7133b6094f96", "status": "succeeded" }, "transaction": { "id": "cxjepxt0ihck2", "amount": 1000, "attempts": [], "with_3ds_params": true, "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "e5iraxm0ajckq", "amount": 1000, "status": "succeeded", "created_at": 1554385200, "extra_data": {} } ], "chargeback": null, "created_at": 1554385200, "currency": "pln", "decline_reason": null, "method": "google_pay", "reference": null, "external_reference": "some_order_reference", "refunded": false, "voided": false, "extra_data": {}, "order_reference": "f8dcfe778c9749cfbe7ea50fc826f202", "authentication_3ds": { "id": "7ejazxs9ae09a", "eci": "05", "errors": [], "status": "succeeded", "created_at": 1554385200, "threeds_v2": { "browser": { "ip": "1.2.3.4", "language": "pl", "timezone": -120, "user_agent": "Mozilla/5.0 (X11; Linux x86_64)", "color_depth": 24, "java_enabled": false, "screen_width": 2560, "accept_header": "*/*", "screen_height": 1440, "javascript_enabled": true } }, "failure_url": "http://example.com/failure", "success_url": "http://example.com/success", "threeds_flow": "frictionless", "protocol_version": "2.1.0", "enrollment_status": "Y" } } } }
{ "event": "checkout_attempt_finished", "data": { "checkout": { "id": "iqxjxcr01hcko", "af_profiling_reference": null, "af_user_reference": null, "amount": 1000, "checkout_url": "https://checkout.straal.com/f4k3", "created_at": 1554385200, "currency": "pln", "customer": { "id": "c0cxh9x04xikh", "last_transaction": { "id": "cxjepxt0ihck2", "authentication_3ds": { "id": "cxjepxt0ihck2" } } }, "extra_data": {}, "failure_url": "https://yourproduct.com/payment_failed", "merchant_image": null, "order_description": "Product F8DCFE77", "order_reference": "f8dcfe778c9749cfbe7ea50fc826f202", "return_url": "https://yourproduct.com/payment_succeeded", "ttl": 600, "use_3ds": true }, "checkout_attempt": { "id": "hj9cxs20d0cki", "authentication_3ds": { "id": "dfa234gatkgh5", "card": null }, "created_at": 1554385200, "profiler_url": null, "session_reference": "778779f3ba974afbab8b7133b6094f96", "status": "succeeded" }, "transaction": { "id": "cxjepxt0ihck2", "amount": 1000, "attempts": [], "with_3ds_params": true, "authorized": true, "pre_auth": false, "captured": true, "captures": [ { "id": "e5iraxm0ajckq", "amount": 1000, "status": "succeeded", "created_at": 1554385200, "extra_data": {} } ], "chargeback": null, "created_at": 1554385200, "currency": "pln", "decline_reason": null, "method": "apple_pay", "reference": null, "external_reference": "some_order_reference", "refunded": false, "voided": false, "extra_data": {}, "order_reference": "f8dcfe778c9749cfbe7ea50fc826f202", "authentication_3ds": { "id": "7ejazxs9ae09a", "eci": "05", "errors": [], "status": "succeeded", "created_at": 1554385200, "threeds_v2": { "browser": { "ip": "1.2.3.4", "language": "pl", "timezone": -120, "user_agent": "Mozilla/5.0 (X11; Linux x86_64)", "color_depth": 24, "java_enabled": false, "screen_width": 2560, "accept_header": "*/*", "screen_height": 1440, "javascript_enabled": true } }, "failure_url": "http://example.com/failure", "success_url": "http://example.com/success", "threeds_flow": "frictionless", "protocol_version": "2.1.0", "enrollment_status": "Y" } } } }
Reconciliations
These notifications are sent only for SEPA Direct Debit transactions.Authorized
Event name: authorizedThis notification is sent when a SEPA Direct Debit transaction is settled.
Sample notification:
{ "event": "authorized", "data": { "transaction": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "eur", "method": "sepa", "authorized": true, "pre_auth": false, "captured": false, "captures": [], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "bank_account": { "id": "83ulegbkuvqmf", "customer": { "id": "mhtaqdb4edvrf" } }, "status": "succeeded", "decline_reason": null, "extra_data": {} }, "timestamp": 1487440567 } }
Authorize failed
Event name: authorize_failedThis notification is sent when a SEPA Direct Debit transaction is declined.
Sample notification:
{ "event": "authorize_failed", "data": { "transaction": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "eur", "method": "sepa", "authorized": false, "captured": false, "captures": [], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "bank_account": { "id": "83ulegbkuvqmf", "customer": { "id": "mhtaqdb4edvrf" } }, "status": "failed", "decline_reason": { "code": 1001, "description": "Declined by issuing bank" }, "extra_data": {} }, "timestamp": 1487440567 } }
Refund succeeded
Event name: refund_succeededThis notification is sent when a SEPA Direct Debit transaction refund is settled.
Sample notification for a partial refund:
{ "event": "refund_succeeded", "data": { "transaction": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "eur", "method": "sepa", "authorized": true, "pre_auth": false, "captured": false, "captures": [], "refunded": false, "refunds": [ { "id": "mkwsfft8hn66y", "created_at": 1472473029, "amount": 900, "status": "succeeded", "extra_data": {} } ], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "bank_account": { "id": "83ulegbkuvqmf", "customer": { "id": "mhtaqdb4edvrf" } }, "status": "partially_refunded", "decline_reason": null, "extra_data": {} }, "timestamp": 1487440567 } }
Sample notification for a full refund:
{ "event": "refund_succeeded", "data": { "transaction": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "eur", "method": "sepa", "authorized": true, "pre_auth": false, "captured": false, "captures": [], "refunded": true, "refunds": [ { "id": "mkwsfft8hn66y", "created_at": 1472473029, "amount": 999, "status": "succeeded", "extra_data": {} } ], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "bank_account": { "id": "83ulegbkuvqmf", "customer": { "id": "mhtaqdb4edvrf" } }, "status": "refunded", "decline_reason": null, "extra_data": {} }, "timestamp": 1487440567 } }
Refund failed
Event name: refund_failedThis notification is sent when a SEPA Direct Debit transaction refund is declined.
Sample notification:
{ "event": "refund_failed", "data": { "transaction": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "eur", "method": "sepa", "authorized": true, "pre_auth": false, "captured": false, "captures": [], "refunded": false, "refunds": [ { "id": "mkwsfft8hn66y", "created_at": 1472473029, "amount": 999, "status": "failed", "extra_data": {} } ], "voided": false, "voids": [], "chargeback": null, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "bank_account": { "id": "83ulegbkuvqmf", "customer": { "id": "mhtaqdb4edvrf" } }, "status": "succeeded", "decline_reason": null, "extra_data": {} }, "timestamp": 1487440567 } }
Chargeback
Event name: sepa_transaction_chargebackThis notification is sent when a SEPA Direct Debit transaction is charged back.
Sample notification:
{ "event": "sepa_transaction_chargeback", "data": { "transaction": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 999, "currency": "eur", "method": "sepa", "authorized": true, "pre_auth": false, "captured": false, "captures": [], "refunded": false, "refunds": [], "voided": false, "voids": [], "chargeback": { "id": "gnranrehp3gl6", "effective_date": 1486684800, "reason_code": "MD06", "reason_description": "Disputed authorised transaction" }, "reference": "b138bc50148440ee", "external_reference": null, "order_reference": null, "bank_account": { "id": "83ulegbkuvqmf", "customer": { "id": "mhtaqdb4edvrf" } }, "status": "chargeback", "decline_reason": null, "extra_data": {} }, "timestamp": 1487440567 } }
Transactions
Card transaction chargeback
Event name: card_transaction_chargebackThis notification is sent when a credit card transaction is charged back.
Sample notification:
{ "event": "card_transaction_chargeback", "data": { "transaction": { "id": "pzhazstgsj497", "attempts": [], "with_3ds_params": false, "created_at": 1521729203, "amount": 999, "currency": "usd", "method": "card", "authorized": true, "pre_auth": false, "captured": true, "refunded": false, "voided": false, "captures": [ { "id": "s2xcew6gsj79p" } ], "refunds": [], "voids": [], "card": { "id": "pzhazstgsj497", "customer": { "id": "s713n8vgsj79p" } }, "chargeback": { "id": "zy8clu5y8bzve", "effective_date": 1577923200, "reason_code": "62", "reason_description": "Counterfeit Transaction", "arn": "12345678901234567890123" }, "reference": "ieph3wow3Hooch4b", "external_reference": null, "order_reference": null, "decline_reason": null, "extra_data": {} }, "timestamp": 1577934248 } }
Card transaction fraud
Event name: card_transaction_fraudThis notification is sent when a credit card transaction has been reported as fraud.
Sample notification:
{ "event": "card_transaction_fraud", "data": { "transaction": { "id": "pzhazstgsj497", "attempts": [], "with_3ds_params": false, "created_at": 1521729203, "status": "fraud_reported", "amount": 999, "currency": "usd", "method": "card", "authorized": true, "pre_auth": false, "captured": true, "refunded": false, "voided": false, "captures": [ { "id": "s2xcew6gsj79p" } ], "refunds": [], "voids": [], "card": { "id": "pzhazstgsj497", "customer": { "id": "s713n8vgsj79p" } }, "reference": "ieph3wow3Hooch4b", "external_reference": null, "order_reference": null, "decline_reason": null, "extra_data": {} }, "timestamp": 1577934248 } }
Card transaction dispute
Event name: card_transaction_disputeThis notification is sent when a credit card transaction has been reported as dispute.
Sample notification:
{ "event": "card_transaction_dispute", "data": { "transaction": { "id": "pzhazstgsj497", "attempts": [], "with_3ds_params": false, "created_at": 1521729203, "status": null, "amount": 999, "currency": "usd", "method": "card", "authorized": true, "pre_auth": false, "captured": true, "refunded": false, "voided": false, "captures": [ { "id": "s2xcew6gsj79p" } ], "refunds": [], "voids": [], "card": { "id": "pzhazstgsj497", "customer": { "id": "s713n8vgsj79p" } }, "reference": "ieph3wow3Hooch4b", "external_reference": null, "order_reference": null, "decline_reason": null, "extra_data": {} }, "timestamp": 1577934248 } }
3DS Redirection
Event name: threeds_redirectionThis notification is sent when 3DS challenge has been initialized. It can arrive faster than synchronous response for transaction.
In data.authentication_3ds.redirect_data you have redirect_url to which the customer must be transferred in order to proceed with transaction.
Sample notification:
{ "event": "threeds_redirection", "data": { "authentication_3ds": { "card": { "id": "5wmjhrgceed97", "customer": { "id": "eajyd5scg7d9c", "last_transaction": { "id": "etfj57mcr7g9d" } } }, "id": "d1c1je5c7759n", "created_at": 1709811679, "currency": "pln", "amount": 1000, "enrollment_status": "Y", "errors": [], "protocol_version": "2.2.0", "redirect_data": { "redirect_url": "https://profiling.url/token" }, "reference": "123asdf123", "straal_custom_data": {}, "subscription": null, "success_url": "http://www.example.merchant_url/success", "failure_url": "http://www.example.merchant_url/fail", "threeds_v2": null, "token_3ds": null } } }
Subscriptions
Recurring payment succeeded
Event name: recurring_payment_succeededThis notification is sent when a recurring payment (i.e. billing according to the subscription's plan) succeeds.
Sample notification:
{ "event": "recurring_payment_succeeded", "data": { "transaction": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 2000, "currency": "usd", "method": "card", "authorized": true, "pre_auth": false, "captured": true, "refunded": false, "voided": false, "captures": [{ "id": "qkymdfy2jbui1", "created_at": 1470239156, "amount": 2000 }], "refunds": [], "voids": [], "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "decline_reason": null, "extra_data": {} }, "subscription": { "id": "m5lwrskt18r4f", "created_at": "1468577492", "active": true, "cancelled_at": null, "cancellation_source": null, "current_period_start": 1468577492, "current_period_end": 1471169492, "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "plan": { "id": "mcn15j2hwhq4f" }, "extra_data": {} } } }
Recurring payment failed
Event name: recurring_payment_failedThis notification is sent when a recurring payment fails.
Sample notification:
{ "event": "recurring_payment_failed", "data": { "transaction": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 2000, "currency": "usd", "method": "card", "authorized": false, "captured": false, "refunded": false, "voided": false, "captures": [], "refunds": [], "voids": [], "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "decline_reason": { "code": 1001, "description": "Declined by issuing bank" }, "extra_data": {} }, "subscription": { "id": "m5lwrskt18r4f", "created_at": "1468577492", "active": true, "cancelled_at": null, "cancellation_source": null, "current_period_start": 1468577492, "current_period_end": 1471169492, "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "plan": { "id": "mcn15j2hwhq4f" }, "extra_data": {} } } }
Subscription cancelled
Event name: subscription_cancelledThis notification is sent when a subscription is cancelled.
Sample notification:
{ "event": "subscription_cancelled", "data": { "subscription": { "id": "m5lwrskt18r4f", "created_at": 1468577492, "active": false, "cancelled_at": 1468671650, "cancellation_source": { "code": 1, "description": "API request" }, "current_period_start": 1468577492, "current_period_end": 1471169492, "card": { "id": "mzivhql5yi9rf", "customer": { "id": "mhtaqdb4edvrf" } }, "plan": { "id": "mcn15j2hwhq4f" }, "extra_data": {}, "straal_custom_data": {} } } }
3DS Subscription Redirection
Event name: threeds_subscription_redirectionThis notification is sent when 3DS challenge must be performed. It can arrive faster than synchronous response for subscription.
In data.authentication_3ds.redirect_data you have redirect_url to which the customer must be transferred
Sample notification:
{ "event": "threeds_subscription_redirection", "data": { "authentication_3ds": { "id": "qjj0j5mngwzf6", "card": { "id": "qw5a8xjnvwvf6", "customer": { "id": "j7y9hj5nqw6f5", "last_transaction": { "id": "wd4j507nyh6fq" } } }, "google_pay": null, "apple_pay": null, "subscription": null, "token_3ds": null, "created_at": 1696233451, "amount": 1000, "currency": "PLN", "reference": "123asdf123", "success_url": "https://merchant.com/asdf/finish_3ds", "failure_url": "https://merchant.com/asdf/finish_3ds", "redirect_data": { "redirect_url": "https://sample-redirect-url.com" }, "enrollment_status": "Y", "protocol_version": "1.0", "threeds_v2": null, "straal_custom_data": {}, "errors": [] }, "csr": { "id": "zkjd56jnxw5fq", "transactions": [ { "id": "wd4j507nyh6fq", "card": { "id": "qw5a8xjnvwvf6", "customer": { "id": "j7y9hj5nqw6f5", "last_transaction": { "id": "wd4j507nyh6fq", "authentication_3ds": { "id": "qjj0j5mngwzf6" } } } }, "authentication_3ds": { "id": "qjj0j5mngwzf6" }, "captures": [ { "id": "wif51sjnq36fi", "status": "pending" } ], "refunds": [], "voids": [], "attempts": [] } ], "created_at": 1696233451, "state": "awaiting_3ds", "errors": [], "antifraud_response": {} } } }
Subscription activated
Event name: subscription_activatedThis notification is sent when subscription was just created and activated, usually send after successful 3DS challenge.
Sample notification:
{ "event": "subscription_activated", "data": { "subscription": { "id": "5avjlhn7ni2kr", "created_at": 1695829043, "active": true, "cancelled_at": null, "current_period_start": 1695829043, "current_period_end": 1698421043, "extra_data": {}, "straal_custom_data": {}, "cancellation_source": null, "start_date": "2023-09-27", "next_planned_charge_date": "2023-10-27", "suspended": false, "plan": { "id": "5niufjs7nrtk2", "created_at": 1695829043, "name": null, "amount": 2000, "currency": "usd", "trial_days": null, "step_type": "month", "step_value": 1 } }, "csr": { "id": "n7w5jjt7t92kr", "state": "final", "transactions": [ { "id": "25i5djt7nzykr", "card": { "id": "5uz2ajh7nr6k2", "customer": { "id": "ni5vzlj74r3k2", "last_transaction": { "id": "25i5djt7nzykr" } } }, "captures": [ { "id": "rm5jttz7f2nk2", "status": "succeeded" } ], "refunds": [], "voids": [], "attempts": [] } ], "errors": [], "antifraud_response": {} } } }
APM payments
APM payment succeeded
Event name: apm_payment_succeededThis notification is sent when an APM payment succeeds.
Sample notification:
{ "event": "apm_payment_succeeded", "data": { "transaction": { "id": "5oubjuaoe6qc4", "voids": [], "amount": 50, "method": "apm", "status": "succeeded", "voided": false, "refunds": [], "attempts": [], "captured": false, "captures": [], "currency": "eur", "pre_auth": false, "refunded": false, "reference": null, "authorized": false, "chargeback": null, "created_at": 1700820692, "extra_data": {}, "apm_payment": { "id": "4tdo5bloj6qcv", "amount": 50, "status": "succeeded", "currency": "eur", "customer": { "id": "57j3xo73n64cq", "last_transaction": { "id": "5oubjuaoe6qc4" } }, "reference": "b13sadkauasdmn", "created_at": 1700820692, "return_url": "https://yourproduct.com/payment_succeeded", "description": "Order 1700820692", "failure_url": "https://yourproduct.com/payment_failed", "redirect_url": "https://apm-authentication-page.com", "origin_ipaddr": "123.123.123.123", "settlement_id": "a6db1dff-cd90-4ea5-9671-8fd528e8889f", "external_reference": "qwert1234", "payment_method_ident": "skrill" }, "decline_reason": null, "order_reference": "b13sadkauasdmn", "with_3ds_params": false, "external_reference": null, "straal_custom_data": {} } } }
APM payment failed
Event name: apm_payment_failedThis notification is sent when an APM payment fails.
Sample notification:
{ "event": "apm_payment_failed", "data": { "transaction": { "id": "q9jmccij3l5cv", "voids": [], "amount": 50, "method": "apm", "status": "failed", "voided": false, "refunds": [], "attempts": [], "captured": false, "captures": [], "currency": "eur", "pre_auth": false, "refunded": false, "reference": null, "authorized": false, "chargeback": null, "created_at": 1700822966, "extra_data": {}, "apm_payment": { "id": "lww5jqejbpkcc", "amount": 50, "status": "failed", "currency": "eur", "customer": { "id": "57j3xo73n64cq", "last_transaction": { "id": "q9jmccij3l5cv" } }, "reference": "b13sadkauasdmn", "created_at": 1700822966, "return_url": "https://yourproduct.com/payment_succeeded", "description": "Order 1700822966", "failure_url": "https://yourproduct.com/payment_failed", "redirect_url": "https://apm-authentication-page.com", "origin_ipaddr": "123.123.123.123", "settlement_id": null, "external_reference": "qwert1234", "payment_method_ident": "skrill" }, "decline_reason": null, "order_reference": "b13sadkauasdmn", "with_3ds_params": false, "external_reference": null, "straal_custom_data": {} } } }
Pay-by-link payments
Pay-by-link payment succeeded
Event name: pay_by_link_payment_succeededThis notification is sent when a pay-by-link payment succeeds.
Sample notification:
{ "event": "pay_by_link_payment_succeeded", "data": { "transaction": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 1499, "currency": "pln", "method": "pay_by_link", "authorized": false, "captured": false, "refunded": false, "voided": false, "captures": [], "refunds": [], "voids": [], "chargeback": null, "reference": null, "external_reference": null, "order_reference": null, "decline_reason": null, "pay_by_link_payment": { "id": "fjdan27fk72na", "created_at": 1472491810, "redirect_url": "https://bank1.example.com", "currency": "pln", "amount": 1499, "return_url": "https://yourproduct.com/payment_succeeded", "failure_url": "https://yourproduct.com/payment_failed", "description": "Order 123123", "reference": "qwerty1234qwerty", "order_reference": null, "origin_ipaddr": "123.123.123.123", "payment_method_ident": "bank1", "external_reference": "ABC123123ABC", "status": "succeeded", "customer": { "id": "mhtaqdb4edvrf", "last_transaction": { "id": "f9g63mazh1wi1" } } }, "extra_data": {} } } }
Pay-by-link payment failed
Event name: pay_by_link_payment_failedThis notification is sent when a pay-by-link payment fails.
Sample notification:
{ "event": "pay_by_link_payment_failed", "data": { "transaction": { "id": "f9g63mazh1wi1", "attempts": [], "with_3ds_params": false, "created_at": 1470238921, "amount": 1499, "currency": "pln", "method": "pay_by_link", "authorized": false, "captured": false, "refunded": false, "voided": false, "captures": [], "refunds": [], "voids": [], "chargeback": null, "reference": null, "external_reference": null, "order_reference": null, "decline_reason": null, "pay_by_link_payment": { "id": "fjdan27fk72na", "created_at": 1472491810, "redirect_url": "https://bank1.example.com", "currency": "pln", "amount": 1499, "return_url": "https://yourproduct.com/payment_succeeded", "failure_url": "https://yourproduct.com/payment_failed", "description": "Order 123123", "reference": "qwerty1234qwerty", "order_reference": null, "origin_ipaddr": "123.123.123.123", "payment_method_ident": "bank1", "external_reference": "ABC123123ABC", "status": "failed", "customer": { "id": "mhtaqdb4edvrf", "last_transaction": { "id": "f9g63mazh1wi1" } } }, "extra_data": {} } } }
Straal Direct Payments
Straal Direct Payment status change
Event name: straal_direct_payment_status_changeThis notification is sent when the status of a Straal Direct Payment has changed. Possible status to results cases:
Notification Statuses and Results
Notification Type | Status | Results |
---|---|---|
Success Notification | initiated |
|
Pending Notification | pending |
|
Failed Notification | failed |
|
Sample notification:
{ "data": { "transaction": { "id": "f9g63mazh1wi1", "amount": 1499, "currency": "eur", "reference": "b13sadkauasdmn", "external_reference": "AJASND-SFLSDJH", "created_at": 1570707755, "extra_data": {}, "order_reference": "MyRef123", "status": "initiated", "straal_direct_payment": { "id": "68clmu86l6zfl", "amount": 1499, "currency": "eur", "customer": { "id": "lccil6ig06ufi", "last_transaction": { "id": "6qcuu6a6p2efl" } }, "external_reference": "AJASND-SFLSDJH", "created_at": 1570707755, "return_url": "https://yourproduct.com/payment_initiated", "description": "Order 123123", "redirect_url": "https://checkout.straal.com/straal_direct_payment_init/some_token", "origin_ipaddr": "123.123.123.123", "merchant_account_number": 123456787, "result": "initialized" } } }, "event": "straal_direct_payment_status_change" }