API Reference

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:
v1.example.permission
Usage
The example below shows a request to get the list of cards for the merchant identified with an (example) API Key: mer_intg_FR2SUXtrnXgOL2KOHzcMQ9U96lJ3Wxjbr3nuvWD1UDNmyxLh.

In cURL: 
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"}
  ]
}
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"}
  ]
}
For requests involving card payments you can find more details about the payment failure by checking the decline_reason field on the returned transaction object.

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
GEThttps://api.straal.com/v1/dummy_objects/g0jk87sc
{
  "id": "g0jk87sc",
  "is_dummy": true,
  "foo": {
    "id": "j5k3jdkwpmz",
    "bar": {
      "id": "j48k502kv"
    }
  }
}
Example request for getting dummy_object with expanded objects
GEThttps://api.straal.com/v1/dummy_objects/g0jk87sc?expand=foo,foo.bar
{
  "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:

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

2024-11-20

2024-10-07

2024-10-07

2024-07-24

2024-07-18

2024-03-XX

2023-11-24

2023-09-11

2023-09-09

2023-09-06

2023-07-24

2023-07-12

2023-06-27

2023-02-23

2021-12-23

2021-09-01

2021-05-17

2021-03-29

2020-12-17

2020-12-01

2020-11-06

2020-10-19

2020-09-14

2020-08-25

2020-06-29

2020-06-16

2020-05-05

2020-04-23

2020-04-20

2020-03-16

2020-03-11

2019-11-21

2019-11-08

2019-10-22

2019-09-16

2019-07-16

2019-07-01

2019-05-24

2019-05-22

2019-04-04

2019-02-18

2018-11-06

2018-10-10

2018-09-17

2018-09-04

2018-08-31

2018-08-22

2018-04-24

2018-04-19

2018-04-04

2018-03-27

2018-02-16

2018-02-15

2018-01-16

2018-01-12

2017-09-13

2017-07-27

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

id
string
Transaction ID
RO
attempts
list
List of previous transaction attempts that have failed
RODEPRECATED
with_3ds_params
boolean
Indicates if charge attempt was with 3DS
RO
transaction_descriptor
string
Description of transaction
RO
created_at
integer
Time at which the object was created
RO
amount
integer
required
Transaction amount
currency
string
required
Transaction currency
type
string
Transaction type (only meaningful for card transactions):
  • 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)
method
string
Transaction method (card, sepa, pay_by_link)
RO
authorized
boolean
Indicates if a v1.transactions.create was successfully authorized
RO
captured
boolean
Indicates if a transaction was fully captured
RO
captures
list
List of capture objects performed within a transaction
RO
refunded
boolean
Indicates if a transaction was fully refunded
RO
refunds
list
List of refund objects performed within a transaction
RO
voided
boolean
Indicates if a transaction was voided
RO
voids
list
List of void objects performed within a transaction
RO
chargeback
object
Chargeback object, if reported
RO
card
object
Card object on which transaction was performed
bank_account
object
Bank account object on which a transaction was performed
status
string
Status of a transaction, available for bank account transactions. Possible values: pending, succeeded, failed
RO
extra_data
object
Additional information about a transaction
reference
string
Your internal transaction reference (has to be unique)
MAXLEN:32UNIQUE
external_reference
string
Unique external transaction reference provided by acquirer
MAXLEN:128UNIQUERO
order_reference
string
Your internal order reference (does not have to be unique)
MAXLEN:32
decline_reason
object
Transaction decline reason, if available
capture
boolean
Indicates if the transaction should be captured. Defaults to true. If set to false, transaction will be authorized, and can be captured in separate capture request
POST ONLY
pre_auth
boolean
Indicates if the transaction should be pre-authorized. Defaults to false.
mpi_params
object
MPI data structure provided by external MPI system if the 3DS authentication has been performed.
authentication_3ds
object
a data structure which can be provided to request a transaction with 3DS. Required keys: success_url, failure_url
initiated_by
string
deprecated
This field is deprecated, use type instead.

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.
POST ONLY
merchant_risk_params
object
Merchant Risk Params data structure containing business information about the transaction purpose.
Additional information for declined transactions is provided in the decline_reason attribute.
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.

POSThttps://api.straal.com/v1/cards/:card_id/transactions
v1.transactions.create
Sample request for a $9.99 transaction 
{
  "amount": 999,
  "currency": "usd",
  "reference": "b138bc50148440ee",
  "type": "oneclick",
  "payment_mean_type": "card"
}
payment_mean_type is optional for 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",
  "transaction_descriptor": "Test*vixrwjoa7gza7",
  "order_reference": null,
  "card": {
    "id": "mzivhql5yi9rf",
    "customer": {
      "id": "mhtaqdb4edvrf"
    }
  },
  "decline_reason": null,
  "extra_data": {}
}
IMPORTANT: a customer's bank can refuse to authorize a transaction without Strong Customer Authentication. In this case we recommend requesting a transaction for previously created card with 3D Secure. Sample Google Pay request for a $9.99 transaction 
{
  "amount": 999,
  "currency": "usd",
  "reference": "b138bc50148440ee",
  "type": "oneclick",
  "payment_mean_type": "google_pay"
}
Sample response: 
{
  "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": {}
}
Sample Apple Pay request for a $9.99 transaction 
{
  "amount": 999,
  "currency": "usd",
  "reference": "b138bc50148440ee",
  "type": "oneclick",
  "payment_mean_type": "apple_pay"
}
Sample response: 
{
  "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.

POSThttps://api.straal.com/v1/cards/:card_id/transactions
v1.transactions.create

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"
      }
    }
  }
}
payment_mean_type is optional for 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": {},
  "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.
protocol_version
string
required
Protocol version, for 3DSv1 should be set to 1.0.
xid
string
required
Transaction ID generated by the 3DSv1 service that uniquely identifies the 3DSecure request.
cavv
string
required
Verification Id of the authentication. Cardholder Authentication Verification Value (CAVV) or Universal Cardholder Authentication Field (UCAF).
eci
string
required
Electronic Commerce Indicator.
mpi_params object for 3DS protocol version 2.
protocol_version
string
required
Protocol version, for 3DSv2 should be set to 2.1.0
xid
string
Transaction ID generated by the 3DSv1 service that uniquely identifies the 3DSecure request.
cavv
string
required
Verification Id of the authentication. Cardholder Authentication Verification Value (CAVV) or Universal Cardholder Authentication Field (UCAF).
eci
string
required
Electronic Commerce Indicator.
ds_transaction_id
string
required
The Directory Server ID used for 3DSecure transactions through the 3DSv2 authentication protocol.
Sample request using create a transaction endpoint
POSThttps://api.straal.com/v1/cards/:card_id/transactions
v1.transactions.create
Sample request for a transaction with 3D-Secure 
{
  "amount": 999,
  "currency": "usd",
  "reference": "b138bc50148440yy",
  "type": "oneclick",
  "mpi_params": {
    "protocol_version": "1.0",
    "xid": "ODUzNTYzOTcwODU5NzY3Qw==",
    "cavv": "jJ81HADVRtXfCBATEp01CJUAAAA=",
    "eci": "05"
  }
}
Sample response 
{
  "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

POSThttps://api.straal.com/v1/customers/:customer_id/transactions
v1.transactions.create_with_card
You can perform a 3D Secure protected transaction by providing an authentication_3ds object containing customer result URLs (success_url and failure_url) in your request payload.
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"
      }
    }
  }
}
The above structure (transaction) is specified here.

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": {}
}
Sample failure response, synchronous (e.g. due to the failed 3DS initialization): 
{
    "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)

POSThttps://api.straal.com/v1/customers/:customer_id/transactions_3ds
v1.transactions.create_with_card_3ds
You can perform a 3D Secure protected transaction by providing an authentication_3ds object containing customer result URLs (success_url and failure_url) in your request payload.

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"
  }
}
The above structure (transaction) is specified here.

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": {}
}
Sample failure response, synchronous (e.g. due to the failed 3DS initialization): 
{
    "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

POSThttps://api.straal.com/v1/customers/:customer_id/transactions
v1.transactions.create_with_card
Sample request for a $9.99 transaction with 3DS 
{
  "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"
      }
    }
  }
}
The above structure (transaction) is specified here. Note that the data received from the digital wallet is sent in the card field. apiVersion, apiVersionMinor, email and paymentMethodData you receive from PaymentData that's returned by Google after a payer approves payment.

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"
}
Sample failure response, synchronous (e.g. due to the failed 3DS initialization): 
{
    "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

POSThttps://api.straal.com/v1/customers/:customer_id/transactions
v1.transactions.create_with_card
Sample request for a $9.99 transaction with 3DS: 
{
  "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"
      }
    }
  }
}
The above structure (transaction) is specified here. Note that the data received from the digital wallet is sent in the card field. token and billingContact you receive from ApplePayPayment that's returned by Apple after a payer approves payment.

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"
}
Sample failure response, synchronous (e.g. due to the failed 3DS initialization): 
{
    "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"
    }
  }
}
The transaction data structure is specified here.

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
POSThttps://api.straal.com/v1/encrypted
The easiest way to do that is to use the Straal.js library.
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"
  }
}
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.

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": {}
    }
  }
}
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": "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"
    }
  }
}
The transaction data structure is specified here.

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
POSThttps://api.straal.com/v1/encrypted
The easiest way to do that is to use the Straal.js library.
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": {}
    }
  }
}
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": "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"
        }
      }
    }
  }
}
The transaction data structure is specified here.

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
POSThttps://api.straal.com/v1/encrypted
The easiest way to do that is to use the Straal.js library.
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
  }
}
apiVersion, apiVersionMinor, email and paymentMethodData you receive from PaymentData that's returned by Google after a payer approves payment.

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"
}
An example of the request_finished notification for a failed 3DS transaction (in this example, the 3DS authentication has failed): 
{
  "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"
        }
      }
    }
  }
}
The transaction data structure is specified here.

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
POSThttps://api.straal.com/v1/encrypted
The easiest way to do that is to use the Straal.js library.
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
  }
}
token and billingContact you receive from ApplePayPayment that's returned by Apple after a payer approves payment.

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"
}
An example of the request_finished notification for a failed 3DS transaction (in this example, the 3DS authentication has failed): 
{
  "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.
acct_info
object
CardholderAccountInformation object object providing additional information about the Cardholder’s account provided by the 3DS Requestor.
browser
object
required
Browser object, representing browser parameters.
merchant_risk_ind
object
MerchantRiskIndicator object - merchant’s assessment of the level of fraud risk for the specific authentication for both the cardholder and the authentication being conducted. Note: Data will be formatted into a JSON object prior to being placed into the Device Merchant Risk Indicator field of the message.
transaction_type
string
Transaction Type - identifies the type of transaction being authenticated. Note: Values derived from the 8583 ISO Standard.
Possible values:
01 - Goods/ Service Purchase
03 - Check Acceptance
10 - Account Funding
11 - Quasi-Cash Transaction
28 - Prepaid Activation and Load
challenge_indicator
string
3DS Requestor Challenge Indicator - indicates whether a challenge is requested for this transaction.

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.
Possible values:
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)
exemption_flag
string
Flags the transaction as exemption during authorization.
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
visa_merchant_id
string
VMID assigned by Visa if participating in Trusted merchant program. Required when exemption value is trusted_merchant

CardholderAccountInformation object - additional information about the Cardholder’s account provided by the 3DS Requestor.
account_age
string
Cardholder Account Age IndicatorPossible values:
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
last_change_date
string
Date that the cardholder’s account with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added.
Length: 8 characters
Format accepted: YYYYMMDD
update_indicator
string
Cardholder Account Change Indicator
Possible values:
01 - Changed during this transaction
02 - Less than 30 days
03 - 30−60 days
04 - More than 60 days
creation_date
string
Date that the cardholder opened the account with the 3DS Requestor.
Length: 8 characters
Format accepted: YYYYMMDD
password_change_date
string
Date that cardholder’s account with the 3DS Requestor had a password change or account reset.
Length: 8 characters
Format accepted: YYYYMMDD
password_change_indicator
string
Indicates the length of time since the cardholder’s account with the 3DS Requestor had a password change or account reset.
Possible values:
01 - No change
02 - Changed during this transaction
03 - Less than 30 days
04 - 30−60 days
05 - More than 60 days
purchases_count_last_6_months
string
Number of purchases with this cardholder account during the previous six months.
Length: maximum 4 characters
provision_attempts_last_24_hours
string
Number of Add Card attempts in the last 24 hours.
Example values:
- 2
- 02
- 002
Length: maximum 3 characters
transactions_activity_last_24_hours
string
Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours. Max 3 characters.
transactions_activity_previous_year
string
Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year. Max 3 characters.
registration_date
string
Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.
Length: 8 characters
Format accepted: YYYYMMDD
registration_indicator
string
Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.
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
shipping_address_date_first_used
string
Date when the shipping address used for this transaction was first used with the 3DS Requestor.
Length: 8 characters
Format accepted: YYYYMMDD
shipping_address_usage_indicator
string
Shipping Address Usage Indicator shipAddressUsageInd: Indicates when the shipping address used for this transaction was first used with the 3DS Requestor.
Possible values:
01 - This transaction
02 - Less than 30 days
03 - 30−60 days
04 - More than 60 days
shipping_address_match_indicator
string
Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.
Possible values:
01 - Account Name identical to shipping Name
02 - Account Name different than shipping Name
suspicious_activity_indicator
string
Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.
Possible values:
01 - No suspicious activity has been observed
02 - Suspicious activity has been observed

The structure of Browser object:
accept_header
string
required
Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser.
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
ip
string
IP address of the browser as returned by the HTTP headers to the 3DS Requestor.
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
language
string
required
Value representing the browser language as defined in IETF BCP47.
Returned from navigator.language property.
Length: Variable, 1–8 characters
user_agent
string
required
Exact content of the HTTP user-agent header.
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.
java_enabled
bool
Boolean that represents the ability of the cardholder browser to execute Java.Value is returned from the navigator.javaEnabled property.Conditional: Required when Browser JavaScript Enabled = true; otherwise Optional.
color_depth
int
Value representing the bit depth of the colour palette for displaying images, in bits per pixel.
Obtained from Cardholder browser using the screen.colorDepth property.
Conditional: Required when Browser JavaScript Enabled = true; otherwise Optional.
screen_height
int
Total height of the Cardholder’s screen in pixels.
Value is returned from the screen.height property.
Conditional: Required when Browser JavaScript Enabled = true; otherwise Optional.
Length: Variable, 1–6 characters; Numeri
screen_width
int
Total width of the cardholder’s screen in pixels.
Value is returned from the screen.width property.
Conditional: Required when Browser JavaScript Enabled = true; otherwise Optional.
Length: Variable, 1–6 characters; Numeric
timezone
int
Time-zone offset in minutes between UTC and the Cardholder browser local time.
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
device_id
string
Unique and immutable identifier linked to a device that is consistent across 3DS transactions for the specific user device.
Length: Variable, up to 64 characters
javascript_enabled
bool
Boolean that represents the ability of the Cardholder Browser to execute JavaScript.
user_id
string
Identifier of the transacting user’s Browser Account ID.
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.
delivery_email_address
string
For Electronic delivery, the email address to which the merchandise was delivered.
Length: maximum 254 characters
delivery_time_frame
string
Indicates the merchandise delivery timeframe.
Possible values:
01 - Electronic Delivery
02 - Same day shipping
03 - Overnight shipping
04 - Two - day or more shipping
gift_card_amount
string
For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).
Example: gift card amount is USD 123.45
Values accepted:
- 123
- 0123
- 00123
Length: maximum 15 characters
gift_card_count
string
For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.
Length: 2 characters
gift_card_curr
string
For prepaid or gift card purchase, ISO 4217 three-digit currency code of the gift card, other that Excluded ISO Currency and Country Code Values (see EMV 3-D Secure Protocol and Core Functions Specification v2.2.0 table A.5.)
Length: 3 characters; numeric
pre_order_date
string
For a pre-ordered purchase, the expected date that the merchandise will be available.
Length: 8 characters
Format accepted: YYYYMMDD
pre_order_pucharse_ind
string
Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
Possible values:
01 - Merchandise available
02 - Future availability
reorder_items_ind
string
Indicates whether the cardholder is reordering previously purchased merchandise.
Possible values:
01 - First time ordered
02 - Reordered
ship_indicator
string
Indicates shipping method chosen for the transaction. Merchants must choose the Shipping Indicator code that most accurately describes the cardholder’s specific transaction, not their general business. If one or more items are included in the sale, use the Shipping Indicator code for the physical goods, or if all digital goods, use the Shipping Indicator code that describes the most expensive item.
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

  1. 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.

  2. 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)

  3. 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.

POSThttps://api.straal.com/v1/customers/:customer_id/transactions
v1.transactions.create_with_card
Sample request for a $9.99 transaction 
{
  "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"
  }
}
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": 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"
    }
  }
}
reference and extra_data are optional.

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
POSThttps://api.straal.com/v1/encrypted
A request containing card data should have the following format: 
{
  "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"
}
You can let your user know immediately if the payment succeeded by checking the HTTP response code.

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:
Airline parameters:
flight_arrival_date
date
Flight arrival date.
YYYY-MM-DD
flight_departure_date
date
Flight departure date
YYYY-MM-DD
airline_code
str
Airline code
airline_flight_number
str
Airline flight number
flight_ticket_number
str
Ticket number
flight_origin_city
str
Flight origin city
flight_destination_city
str
Flight destination city
airline_tour_operator_name
str
Tour operator name
Event parameters:
event_start_date
date
Event start date
YYYY-MM-DD
event_end_date
date
Event end date
YYYY-MM-DD
event_organizer_id
str
ID of event organizer
event_id
str
ID of event
Furniture parameters:
date_of_order
date
Date the order has been created
YYYY-MM-DD
delivery_date
date
Date of delivery
YYYY-MM-DD
name_of_the_supplier
str
Supplier name
Hotels and Real estate rentals parameters:
check_in_date
date
Check-in date
YYYY-MM-DD
check_out_date
date
Check-out date
YYYY-MM-DD
travel_agency_name
str
Name of travel agency
Car, Plane and Boat Rentals parameters:
vehicle_pick_up_date
date
Date of planned vehicle pick-up
YYYY-MM-DD
vehicle_return_date
date
Date of planned vehicle return
YYYY-MM-DD
supplier_name
str
Name of the vehicle supplier
Cruise agencies parameters:
cruise_start_date
date
Cruise start date
YYYY-MM-DD
cruise_end_date
date
Cruise end date
YYYY-MM-DD
Travel agencies parameters:
arrival_date
date
Date of arrival
YYYY-MM-DD
departure_date
date
Date of departure
YYYY-MM-DD
carrier_code
str
Carrier code
flight_number
str
Flight number
ticket_number
str
Ticket number
origin_city
str
Origin city
destination_city
str
Destination city
travel_agency
str
Travel agency name
contractor_name
str
Name of contractor
atol_certificate
str
ATOL certificate number
pick_up_date
date
Date of pick-up
YYYY-MM-DD
return_date
date
Date of return
YYYY-MM-DD
All dates should be formatted using the ISO-8601 (extended) format (i.e. YYYY-MM-DD). Other fields may have format specifications specific to the acquirer.
Example request using create a transaction endpoint
POSThttps://api.straal.com/v1/cards/:card_id/transactions
v1.transactions.create
Sample request: 
{
  "amount": 999,
  "currency": "usd",
  "reference": "b138bc50148440yy",
  "type": "oneclick",
  "merchant_risk_params": {
    "departure_date": "2021-01-13",
    "arrival_date": "2021-01-18"
  }
}
Sample response 
{
  "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.
GEThttps://api.straal.com/v1/transactions/:transaction_id
v1.transactions.get
Sample response: 
{
  "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.
GEThttps://api.straal.com/v1/transactions
v1.transactions.list
Sample response (limited to 2 objects):
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.
GEThttps://api.straal.com/v1/customers/:customer_id/transactions
v1.transactions.customer_list
Sample response (limited to 2 objects):
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.
GEThttps://api.straal.com/v1/cards/:card_id/transactions
v1.transactions.card_list
Sample response (limited to 2 objects):
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.
GEThttps://api.straal.com/v1/subscriptions/:subscription_id/transactions
v1.transactions.subscription_list
Sample response (limited to 2 objects):
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.
id
string
Id of the 3D-Secure authentication object
protocol_version
string
Protocol version
threeds_v2
object
3D-Secure v2 parameters (threeds_v2 object)
card
object
Card object on which transaction was performed
subscription
object
Additional information about subscription
token_3ds
object
Additional information about transaction
created_at
integer
Time at which the object was created
amount
integer
Transaction amount
currency
string
Transaction currency
reference
string
Your internal transaction reference (has to be unique)
success_url
string
URL to redirect to after successful 3D-Secure authentication (redirects to this URL do not indicate that the transaction succeeded, only that the Strong Customer Authentication (SCA) has been completed successfully)
failure_url
string
URL to redirect to after failed 3D-Secure authentication
enrollment_status
string
Enrollment status of the card
status
string
Status of 3D-Secure authentication
eci
string
ECI code indicating result of authentication attempt (if provided by Payment Facilitator)
threeds_flow
string
Type of authentication flow (if provided by Payment Facilitator)
straal_custom_data
object
Your additional information for the 3D-Secure authentication
RO
errors
list
List of errors related to the 3D-Secure process

[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).
  1. Initialize the 3D-Secure process.
  2. Customer is redirected to their issuing bank for the purpose of Strong Customer Authentication (SCA).
  3. 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.
  4. 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.
  5. 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
POSThttps://api.straal.com/v1/cryptkeys
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 the 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.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"
    }
  }
}
transaction.reference and transaction.extra_data are optional.

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
POSThttps://api.straal.com/v1/encrypted
The easiest way to do that is to use the Straal.js library.
A request containing card data should have the following format: 
{
  "name": "John Smith",
  "number": "4444444444444448",
  "cvv": "123",
  "expiry_month": 11,
  "expiry_year": 2020
}
The response body will contain a request_id field which should be matched later on with the request_finished notification. 
{
  "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"
    }
  }
}
The data.response key represents the 3D-Secure authentication object.

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.
GEThttps://api.straal.com/v1/authentications_3ds/:authentication_3ds_id
v1.authentications_3ds.get
Sample response: 
{
  "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.
POSThttps://api.straal.com/v1/authentications_3ds/:authentication_3ds_id/finalize_transaction
v1.transactions.create_from_3ds_auth
The request body should be empty. Response body describes a Transaction object.

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

id
string
Capture ID
RO
created_at
integer
Time at which the capture object was created
RO
amount
integer
Amount to capture. If not set, full capture will be performed
status
string
Capture status. It may have one of the following values: succeeded, failed or cancelled
RO
extra_data
object
Additional information about capture

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.
POSThttps://api.straal.com/v1/transactions/:transaction_id/capture
v1.transactions.capture
Sample request for full capture with extra_data. 
{
  "extra_data": {
    "custom_field": "value"
  }
}
Sample 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": 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.
POSThttps://api.straal.com/v1/transactions/:transaction_id/capture
v1.transactions.capture
Sample request for a partial capture: 
{
  "amount": 499
}
Sample 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": 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

id
string
Refund ID
RO
created_at
integer
Time at which the object was created
RO
amount
integer
Amount to refund. If not set, full refund will be performed
status
string
Refund status. It may have one of the following values: succeeded, pending or failed
RO
extra_data
object
Additional information about the refund. It might be useful to store e.g. information about the refund reason.

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.
POSThttps://api.straal.com/v1/transactions/:transaction_id/refund
v1.transactions.refund
Sample request for full refund with extra_data. 
{
  "extra_data": {
    "reason": "cancellation"
  }
}
Sample 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"
    }
  ],
  "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": {}
}
It is also possible to make a full refund without extra_data by just sending a POST request with an empty body.

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.
POSThttps://api.straal.com/v1/transactions/:transaction_id/refund
v1.transactions.refund
Sample request for a partial refund: 
{
  "amount": 499
}
Sample 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"
    }
  ],
  "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

id
string
Card object ID
RO
created_at
integer
Time at which the object was created
RO
state
string
State of card ("active"/"disabled")
RO
state_flags
list
List of reasons why the card is disabled, if any
RO
brand
string
Credit card brand
RO
name
string
required
Cardholder name on card
number
string
required
Credit card number, required on card creation
POST ONLY
num_bin
string
6 digits Card BIN number (based on posted number)
RO
num_last_4
string
Last 4 digits of card number (based on posted number)
RO
cvv
string
Card security code, used only on card creation
POST ONLY
expiry_month
int
required
Card expiration month (format: 1-12)
expiry_year
int
required
Card expiration year (in YYYY format)
origin_ipaddr
string
required conditionally
IP address from which the card was created. Required only if the request is sent from your backend
RO
customer
object
Credit card owner
EXPANDABLE
extra_data
object
Additional information about the card
verification_transaction
object
Object sent to override default verification transaction amount settings
POST ONLY
billing_address
object
Card billing address data
tokenization
object
Tokenization data

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.
amount
integer
Verification transaction amount
currency
string
Verification transaction currency
type
string
Verification transaction type. Defaults to oneclick.

Tokenization object attributes

purpose
string
Purpose of tokenization. Only init_payment purpose is supported

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.
street_addr
string
First line of street address
street_addr_2
string
Second line of street address
city
string
City
state_or_province
string
State or province
state_or_province_code
string
State or province code
postal_code
string
Postal/zip code
country
string
Country name
country_code
string
Country code (ISO 3166-1 two-letter)

Create a card

Creates a card for a specified customer ID.
POSThttps://api.straal.com/v1/customers/:customer_id/cards
v1.cards.create
Sample request: 
{
  "name": "John Smith",
  "number": "4444444444444448",
  "cvv": "123",
  "expiry_month": 11,
  "expiry_year": 2023,
  "origin_ipaddr": "91.17.133.219"
}
Sample response: 
{
  "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": {}
}
Sample request with billing address: 
{
  "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"
  }
}
Sample response: 
{
  "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"
    }
  }
}
extra_data parameter of card is optional so you don't have to include the card object at all.

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
POSThttps://api.straal.com/v1/encrypted
Example request payload containing card data: 
{
  "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"
}
You can let your user know immediately if payment succeeded by checking the HTTP response code.

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.
POSThttps://api.straal.com/v1/customers/:customer_id/cards
v1.cards.create
Sample request: 
{
  "name": "John Smith",
  "number": "4444444444444448",
  "cvv": "123",
  "expiry_month": 11,
  "expiry_year": 2023,
  "origin_ipaddr": "91.17.133.219",
  "tokenization": {"purpose": "init_payment"}
}
Sample response: 
{
  "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": []
      }
  ]
}
Created card has awaiting_initial_transaction state. When initial transaction is completed, card state changes to active. If you don't complete the initial transaction, the card status will be changed to disabled 24 hours after card creation. Initial transaction can be completed by creating transaction or subscription

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"}
  }
}
After sending CryptKey request with additional purpose: "init_payment" parameter, CryptKey flow can be applied.

Get a card

Returns information of a specified card.
GEThttps://api.straal.com/v1/cards/:card_id
v1.cards.get
Sample response: 
{
    "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.
GEThttps://api.straal.com/v1/cards
v1.cards.list
Sample response (limited to 3 objects):
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.
GEThttps://api.straal.com/v1/customers/:customer_id/cards
v1.cards.customer_list
Sample response (limited to 3 objects):
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.
POSThttps://api.straal.com/v1/cards/:card_id/disable
v1.cards.disable
Sample request: 
{
  "initiated_by": "customer"
}
Sample response: 
{
  "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

id
string
Payment Mean object ID
RO
created_at
integer
Time at which the object was created
RO
brand
string
Credit card brand
RO
num_bin
string
6 digits Card BIN number
RO
num_last_4
string
Last 4 digits of card number
RO
expiry_month
int
Card expiration month (format: 1-12)
RO
expiry_year
int
Card expiration year (in YYYY format)
RO
origin_ipaddr
string
IP address from which the payment_mean was created
RO

Get a Payment Mean

Returns information of a specified payment mean associated with a digital wallet.
GEThttps://api.straal.com/v1/payment_means/:payment_mean_id
v1.payment_means.get
Sample response, after successful transaction for Google Pay payment: 
{
    "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"
}
Sample response, after failed transaction for Google Pay payment: 
{
    "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"
}
Sample response, after successful transaction for Apple Pay payment: 
{
    "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"
}
Sample response, after failed transaction for Apple Pay payment: 
{
    "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.
GEThttps://api.straal.com/v1/customers/:customer_id/payment_means
v1.payment_means.customer_list
Sample response (limited to 3 objects):
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

id
string
ID of the customer object
RO
created_at
integer
Time at which the object was created
RO
email
string
required
Customer email address
reference
string
Your internal customer reference (has to be unique)
MAXLEN:32UNIQUE
external_reference
string
Your external customer reference
MAXLEN:255
last_transaction
object
Customer last transaction
EXPANDABLE

Create a customer

POSThttps://api.straal.com/v1/customers
v1.customers.create
Sample request: 
{
  "email": "[email protected]",
  "reference": "auIj01kcj98lfq",
  "external_reference": "dsa9d6ca9ds"
}
Sample response: 
{
  "id": "mhtaqdb4edvrf",
  "created_at": 1467716585,
  "email": "[email protected]",
  "reference": "auIj01kcj98lfq",
  "external_reference": "dsa9d6ca9ds"
}

Get a customer

Returns a customer for a specified ID.
GEThttps://api.straal.com/v1/customers/:customer_id
v1.customers.get
Sample response: 
{
  "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.
GEThttps://api.straal.com/v1/customers
v1.customers.list
Sample response (limited to 2 objects):
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

id
string
ID of the subscription object
RO
created_at
integer
Time at which the object was created
RO
current_period_start
integer
-
RO
current_period_end
integer
-
RO
active
boolean
Indicates if subscription is active
cancelled_at
integer
Time at which the subscription was cancelled
RO
cancellation_source
object
The code and description of the cancellation reason (see the table below)
RO
plan_id
string
required
ID the of the plan object
POST ONLY
card
object
Card associated with the subscription
EXPANDABLE
bank_account
object
Bank account associated with the subscription
EXPANDABLE
plan
object
Plan associated with the subscription
EXPANDABLE
extra_data
object
Optional additional information about the subscription
straal_custom_data
object
Information relating to custom Straal integrations
RO
start_date
date
If set, the first subscription period, or trial, will be calculated starting from this future date.
Allowed data types: timestamp or ISO formatted date ("YYYY-MM-DD")
start_date
date
If set, the first subscription period, or trial, will be calculated starting from this future date.
Allowed data types: timestamp or ISO formatted date ("YYYY-MM-DD")
mpi_params
object
MPI data structure provided by external MPI system if the 3DS authentication has been performed.

Available cancellation_source codes

1
API request
2
Antifraud rules
5
Received a fraud response for a transaction
6
Fraud reported
7
Chargeback
8
Credit card expired

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.
POSThttps://api.straal.com/v1/cards/:card_id/subscriptions
v1.subscriptions.create
Sample request: 
{
  "plan_id": "mcn15j2hwhq4f"
}
Sample response: 
{
  "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.
POSThttps://api.straal.com/v1/customers/:customer_id/subscriptions
v1.subscriptions.create_for_customer
Sample request: 
{
  "plan_id": "mcn15j2hwhq4f",
  "card": {
    "name": "Samwell Gordon",
    "number": "4444333322221111",
    "cvv": "789",
    "expiry_month": 7,
    "expiry_year": 2019,
    "origin_ipaddr": "54.4.125.235"
  }
}
Sample response: 
{
  "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": {}
}
Sample error response: 
{
  "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
POSThttps://api.straal.com/v1/customers/:customer_id/subscriptions
v1.subscriptions.create_for_customer
You can perform a 3D Secure using your own 3DS provider. Then you have to attach mpi_params to the card object in the request body.

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"
     }
  }
}
Sample response: 
{
  "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.
POSThttps://api.straal.com/v1/cards/:card_id/subscribe
v1.subscriptions.create_v2
Sample request: 
{
  "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": ""
      }
    }
  }
}
Sample response with 3DS redirect: 
{
  "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"
  }
}
Sample response when 3DS is not required: 
{
  "csr": {
    "id": "a1w9e3nqstkaw",
    "subscription": {
        "id": "a149e3nq89kaw"
    },
    "transactions": [
      {
        "id": "f9g63mazh1wi1"
      }
    ],
    "extra_data": {},
    "straal_custom_data": {}
  },
  "authentication_3ds": null
}
Sample error response: 
{
  "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
}
Or: 
{
  "errors": [
    {
      "message": "Failed to decode JSON in HTTP request",
      "code": 95001
    }
  ]
}

Get a subscription

Returns details of an existing subscription.
GEThttps://api.straal.com/v1/subscriptions/:subscription_id
v1.subscriptions.get
Sample response: 
{
  "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.
GEThttps://api.straal.com/v1/subscriptions
v1.subscriptions.list
Sample response (limited to 2 objects):
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.
GEThttps://api.straal.com/v1/customers/:customer_id/subscriptions
v1.subscriptions.customer_list
Sample response (limited to 3 objects):
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.
GEThttps://api.straal.com/v1/cards/:card_id/subscriptions
v1.subscriptions.card_list
Sample response (limited to 3 objects):
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.
GEThttps://api.straal.com/v1/subscribe_status/:csr_id
v1.subscriptions.status
Sample response with redirect_url and successfully created subscription:: 
{
  "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"
  }
}
Sample response with redirect_url and without subscription (next step is to redirect Merchant to 3DS Challange): 
{
  "csr": {
    "id": "439to9r0ezfwq",
    "subscription": null,
    "transactions": [
      {
        "id": "834bhfr0eznsy"
      }
    ],
    "extra_data": {},
    "straal_custom_data": {}
    },
  "authentication_3ds": {
    "id": "84cjj3483d3fa",
    "redirect_url": "https://sample-redirect-url.com"
  }
}
Sample response without redirect_url (send requests until you get response with redirect_url at least): 
{
  "csr": {
    "id": "439to9r0ezfwq",
    "subscription": null,
    "transactions": [
      {
        "id": "834bhfr0eznsy"
      }
    ],
    "extra_data": {},
    "straal_custom_data": {}
    },
  "authentication_3ds": {
    "id": "84cjj3483d3fa",
    "redirect_url": null
  }
}
Sample response with error (stop pooling for redirect_url, because subscription cannot be created): 
{
  "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.
POSThttps://api.straal.com/v1/subscriptions/:subscription_id/cancel
v1.subscriptions.cancel
Sample response: 
{
  "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

id
string
Plan object ID
RO
created_at
integer
Time at which the object was created
RO
name
string
Optional plan name
MAXLEN:128
amount
integer
required
Defines amount of recurring transactions
currency
string
required
Defines currency of recurring transactions
trial_days
integer
Trial period
step_type
string
required
Either "day", "month"` or "year"
step_value
integer
required
How many of step_type make a billing period

Create a plan

POSThttps://api.straal.com/v1/plans
v1.plans.create
Sample request for creating $19.99 monthly plan with a 7-day trial period. 
{
  "name": "Regular monthly $19.99",
  "amount": 1999,
  "currency": "usd",
  "trial_days": 7,
  "step_type": "month",
  "step_value": 1
}
Response: 
{
  "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.
GEThttps://api.straal.com/v1/plans/:id
v1.plans.get
Sample response: 
{
  "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.
GEThttps://api.straal.com/v1/plans
v1.plans.list
Sample response (limited to 2 objects):
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

id
string
Checkout object ID
RO
created_at
integer
Time at which the object was created
RO
currency
string
required
Transaction currency
amount
integer
required
Transaction amount
ttl
integer
required
Checkout expiration time (in seconds)
MINVAL:60MAXVAL:1200
return_url
string
required
User will be redirected to this URL after successful payment
failure_url
string
required
User will be redirected to this URL after failed payment
order_description
string
Description of an order - this information will be visible on the checkout page form
order_reference
string
Reference of an related order - this information will be visible on the checkout page form
checkout_url
string
URL of the checkout page, you should redirect your user to this address
RO
lang
string
If provided, user will be initially shown the checkout page in this language (supported values: cs, de, dk, en, es, fi, fr, hr, hu, it, lt, lv, nl, no, pl, pt, ro, ru, se).
POST ONLY
attempts
list
List of user attempts
RO
card_transaction
object
Parameters specific to card transactions, ignored if other payment method is selected by customer. Parameter "type" defaults to oneclick and can take value oneclick or oneshot.
POST ONLY
extra_data
object
Additional information about the checkout

Card transaction object attributes

type
string
Card transaction type. Can take values oneclick or oneshot. Defaults to oneclick.

Initialize checkout

POSThttps://api.straal.com/v1/customers/:customer_id/checkouts
v1.checkouts.create
Sample request: 
{
  "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"
  }
}
Sample response: 
{
  "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

GEThttps://api.straal.com/v1/checkouts/:checkout_id
v1.checkouts.get
Sample response for Card payment: 
{
  "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"
        }
      }
    }
  ]
}
Sample response for Google Pay payment: 
{
  "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"
        }
      }
    }
  ]
}
Sample response for Apple Pay payment: 
{
  "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

id
string
Card object ID
RO
created_at
integer
Time at which the object was created
RO
key
string
Key used to encrypt the data.
RO
ttl
integer
Key expiration time (in seconds)
RO
permission
string
required
Valid request permission string

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.
POSThttps://api.straal.com/v1/cryptkeys
v1.cryptkeys.create
Sample request: 
{
  "permission": "v1.cards.create",
  "customer_id": "mzivhql5yi9rf"
}
Sample response (key attribute is shortened): 
{
  "id": "70xfzmynzgkih",
  "created_at": 1470302857,
  "key": "06c5fbc1a9800003ba(...)",
  "af_attempt_reference": "01TGR3VANKBBAQRCJNMRA1T2R9",
  "permission": "v1.cards.create",
  "ttl": 600
}
Use af_attempt_reference value if you integrate an anti-fraud profiler on your frontend. In this case, pass this value to the frontend and use it as an argument of profiler's initialisation function.

Usage

Every request encrypted with CryptKey should be sent to special endpoint:
POSThttps://api.straal.com/v1/encrypted
Read more detailed usage examples:
- 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

id
string
CSR ID
RO
created_at
integer
Time at which the object was created
RO
card
object
Card object to charge subscription fees
RO
bank_account
object
Bank account object to charge subscription fees
RO
plan
string
Subscription plan object
RO
errors
list
List of errors related to this CSR
RO
antifraud_response
object
Information from the antifraud system
RO
transactions
list
List of transaction objects related to this CSR
RO
subscription
object
Subscription object created by this CSR
RO

Get a CSR

Returns details of a CSR.
GEThttps://api.straal.com/v1/csrs/:csr_id
v1.csrs.get
Sample response: 
{
  "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.
GEThttps://api.straal.com/v1/csrs
v1.csrs.list
Sample response (limited to 2 objects):
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

id
string
APM payment ID
RO
created_at
integer
Time at which the object was created
RO
redirect_url
string
URL to which the end user has to be redirected to make a payment
RO
payment_method_ident
string
required
Ident of the payment method selected by the end user
amount
integer
required
Transaction amount
currency
string
required
Transaction currency
return_url
string
required
URL to which the end user will be redirected after payment has been successfully initiated. The final payment status will be sent in APM notifications.
failure_url
string
URL to which the end user will be redirected after failure in the synchronous payment process. If not provided, the end user will be redirected to return_url instead.
origin_ipaddr
string
required
IP address from which the APM payment was created
description
string
required
Description of the payment
reference
string
required
Merchant payment reference
language
string
Language in which payment will be processed. Used only for bank_transfer type of payment method. (supported values: cs, de, dk, en, es, fi, fr, hr, hu, it, lt, lv, nl, no, pl, pt, ro, ru, se).
billing_details
object
Customer billing details. Used only for apm type of payment method
merchant_descriptor
object
This is the merchant descriptor that will be displayed on the customer card or bank statement. Used only for apm type of payment method
external_reference
string
Payment reference that can be shown to the end user. This reference will be used in the notification email sent to the end user for bank_transfer type of payment method.
RO
status
string
Current status of the payment. Possible values: new, pending, succeeded, failed
RO
customer
object
Customer for whom the payment is created
ROEXPANDABLE

Initialize an APM payment

This method allows you to initialize an APM payment for a previously created customer object.
POSThttps://api.straal.com/v1/customers/{customer_id}/apm
v1.apm_payments.create
Sample request with optional attributes initializing APM payment. 
{
  "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"
  }
}
Sample response: 
{
    "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"
}
A pay-by-link payment object represents a pay-by-link payment attempt made by a customer.

Pay-by-link payment object attributes

id
string
Pay-by-link payment ID
RO
created_at
integer
Time at which the object was created
RO
redirect_url
string
URL to which the end user has to be redirected to make a payment
RO
payment_method_ident
string
Ident of the payment method selected by the end user
amount
integer
Transaction amount
currency
string
Transaction currency
return_url
string
URL to which the end user will be redirected after successful payment
failure_url
string
URL to which the end user will be redirected after failed payment. If not provided, the end user will be redirected to `return_url` in both cases.
origin_ipaddr
string
IP address from which the pay-by-link payment was created
description
string
Description of the payment
reference
string
Merchant payment reference
external_reference
string
Payment reference that can be shown to the end user. This reference will be used in the notification email sent to the end user, etc.
RO
status
string
Current status of the payment. Possible values: pending, succeeded, failed
RO
customer
object
Customer for whom the payment is created
ROEXPANDABLE
Deprecated in favor of generic APM.

This method allows you to initialize a pay-by-link payment for a previously created customer object.
POSThttps://api.straal.com/v1/customers/{customer_id}/pay_by_link_payments
v1.pay_by_link_payments.create
Sample request initializing pay-by-link payment. 
{
  "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"
 }
Sample response: 
{
  "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

ident
string
ID of the payment method
RO
type
string
Type of the payment method. Possible values: card, apm and bank_transfer.
RO
description
string
Human-readable name of the payment method
RO
supported_currencies
array of strings
Array of ISO 4217 currency codes which are supported for the payment method
RO
image_url
string
URL of the image (bank logo etc.) that can be shown to the end user in the payment method selection view
RO
status
string
Status of the payment method. enabled means that you can use that method to make transactions. temporary_disabled means that it is not available at the moment but should be available soon.
RO
meta
object
An object containing additional info related to the payment method. For card payment it might be a list of supported_card_brands, for apm and bank_transfer payment methods it will be empty.
RO

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.
GEThttps://api.straal.com/v1/payment_methods
v1.payment_methods.list
Sample response: 
[
  {
    "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"
  }
]
It is possible to change or limit payment methods list using these GET parameters:
currency
string
Currency code in ISO 4217 format. After using this filter the results will show only payment methods that support given currency.
type
string
Payment methods type (card, apm or bank_transfer). Only payment methods with given type will be returned.
language
string
2-letter ISO language code. Supported languages: en, pl.

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

id
string
Void ID
RO
created_at
integer
Time at which the object was created
RO
status
string
Void status. It may have one of the following values: succeeded or failed
RO
extra_data
object
Additional information about void

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.
POSThttps://api.straal.com/v1/transactions/:transaction_id/void
v1.transactions.void
Sample request for void with extra_data. 
{
  "extra_data": {
    "custom_field": "value"
  }
}
Sample response: 
{
  "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

id
string
Credit object ID
RO
created_at
integer
Time at which the object was created
RO
currency
string
Credit currency (same as original transaction currency)
RO
amount
integer
required
Credit amount
reference
string
required
Unique credit reference sent to acquirer, should be alphanumeric
MAXLEN:32UNIQUE
description
string
Description of a credit
status
string
Credit status. It may have one of the following values: succeeded, pending or failed
RO
errors
list
List of errors related to this credit
RO
original_transaction
Transaction
Transaction referenced in credit order, contains nested IDs of card and customer
RO
extra_data
object
Additional information about the credit

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.
POSThttps://api.straal.com/v1/transactions/:transaction_id/credits
v1.credits.create
Sample request for a 9.99 credit 
{
  "amount": 999,
  "reference": "b138bc50148440ee",
  "description": "Winnings from 2021-05"
}
Sample response: 
{
  "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

GEThttps://api.straal.com/v1/credits/:credit_id
v1.credits.get
Sample response: 
  {
    "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.
GEThttps://api.straal.com/v1/credits
v1.credits.list
Sample response (limited to 2 objects):
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.
GEThttps://api.straal.com/v1/transactions/:transaction_id/credits
v1.transactions.credits_list
Sample response (limited to 2 objects):
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.
GEThttps://api.straal.com/v1/customers/:customer_id/credits
v1.customers.credits_list
Sample response (limited to 2 objects):
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

id
string
Straal Direct payment ID
RO
created_at
integer
Time at which the object was created
RO
redirect_url
string
URL to which the end user has to be redirected to make a payment
RO
amount
integer
required
Transaction amount
currency
string
required
Transaction currency
return_url
string
required
URL to which the end user will be redirected after initiated payment
origin_ipaddr
string
required
IP address from which the Straal Direct payment was created
description
string
required
Description of the payment
reference
string
required
Your internal transaction reference (has to be unique)
MAXLEN:32UNIQUE
order_reference
string
Your internal order reference (does not have to be unique)
MAXLEN:32
external_reference
string
Payment reference that can be shown to the end user. This reference will be used in the notification email sent to the end user, etc.
RO
status
string
Current status of the payment. Possible values: pending, initiated, failed
RO
customer
object
Customer for whom the payment is created
ROEXPANDABLE
transaction
object
Transaction associated with created Straal Direct Payment
RO
country_code
string
Preselected country code that will be chosen for Customer (ISO 3166-1 two-letter)
institution_id
string
Preselected institution that will be chosen for the Customer
customer_name
string
required
Customer name
MAXLEN:1024
merchant_account_number
string
required
Merchants account number to which the funds are to be transferred.
institution_group_name
string
Institutions are filtered by group name. Must always be provided together with the country code. Example: Sparkasse
account_identifiers
object
Customer account identifiers. Allowed values: iban, psu_id, branch_code, account_number, psu_ip_address

Keep in mind

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.
POSThttps://api.straal.com/v1/customers/{customer_id}/straal_direct_payments
v1.straal_direct_payments.create
Sample request starting a Straal Direct payment. 
{
   "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",
   "institution_group_name": "Sparkasse",
   "account_identifiers": {
      "iban": "PL60394020300000394003494444",
      "psu_id": "1252423",
      "branch_code": "123",
      "account_number": "12345678",
      "psu_ip_address": "123456"
   }
 }
Sample response: 
{
   "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.
POSThttps://api.straal.com/v1/transactions
v1.transactions.create_with_card_and_customer
Sample request for a $9.99 transaction 
{
  "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"
    }
  }
}
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": 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

POSThttps://api.straal.com/v1/cards
v1.cards.create_with_customer
Sample request: 
{
  "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"
  }
}
Sample response: 
{
  "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.
POSThttps://api.straal.com/v1/subscriptions
v1.subscriptions.create_with_card_and_customer
Sample request: 
{
  "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"
    }
  }
}
Sample response: 
{
  "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": {}
}
Sample error response: 
{
  "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 GitHub

Usage

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_finished

If 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": {}
    }
  }
}
Sample notification for Google Pay transaction: 
{
  "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": {}
      }
    }
  }
}
Sample notification for Apple Pay transaction: 
{
  "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_finished

This 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": {}
    }
  }
}
Sample notification for Google Pay 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",
        "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"
      }
    }
  }
}
Sample notification for Apple Pay 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",
        "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: authorized

This 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_failed

This 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_succeeded

This 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_failed

This 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_chargeback

This 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_chargeback

This 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_fraud

This 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_dispute

This 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_redirection

This 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_succeeded

This 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_failed

This 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_cancelled

This 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_redirection

This 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_activated

This 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_succeeded

This 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_failed

This 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": {}
    }
  }
}
Event name: pay_by_link_payment_succeeded

This 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": {}
    }
  }
}
Event name: pay_by_link_payment_failed

This 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_change

This 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
  • initialized
Pending Notification pending
  • bank_redirect
  • delayed_at_bank
  • additional_authorisation_required
Failed Notification failed
  • refused_by_risk
  • refused_by_bank
  • error_at_bank
  • cancelled_by_user
  • abandoned_by_user
  • 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"
}