Skip to content

Code integration🔗︎

This page provides the information required to connect RaiAccept to your e-commerce platform via API and integrate the payment form.

Before you begin🔗︎

Before you start configuring the API calls, generate a set of store credentials and prepare redirect links from the payment form.

Click to expand for how to prepare redirect links

To enable the best shopping experience with RaiAccept, it is necessary that you prepare the following landing pages to redirect the consumer to. Include the order number in the URL to create a personalized shopping experience for your consumers.

  • SUCCESS – URL to redirect the consumer in case of a successful transaction
  • FAILURE – URL to redirect the consumer in case of an unsuccessful transaction
  • CANCEL – URL to redirect the consumer in case the transaction is cancelled

RaiAccept can also send webhook notifications about the transaction result to your e-commerce platform. To use this feature, prepare a notification URL that is configured to receive HTTP webhooks.

Checkout API resource🔗︎

RaiAccept uses REST API to provide communication with your e-commerce platform. When a consumer starts a card payment, your e-commerce platform requests RaiAccept to authenticate and then to create order entry and payment form session.

Optionally, you can retrieve the order details as they were stored in the RaiAccept database.

The order of API communication is as follows:

  1. Perform authentication and retrieve token
  2. Create order entry with unique order ID
  3. Create payment form session

Info

RaiAccept creates a database entry for the order and creates the checkout session in two separate steps – POST requests. This brings several benefits:

  • The order details are stored in RaiAccept database and may be retrieved and used later.
  • The order is separated from the payment itself, so you can see the incomplete order or unsuccessful payment in the Merchant portal.
  • In the future, consumers will be able to leave the e-commerce platform and return to the payment window later without losing the order.

Make sure you use the same parameters and their values for Create order entry and for Create payment session request.

Info

The fields marked Recommended are optional for RaiAccept API to work and RaiAccept can process payments without them. Sending the Recommended fields increases the chance that the consumer’s card issuing bank allows a 3-D Secure frictionless payment (without a requirement to type a password or confirm the transaction in mobile banking app) that makes for a smoother shopping experience for the consumer.

1. Authentication🔗︎

RaiAccept uses Amazon Cognito service to verify the merchant’s credentials and to create an authentication token to use in the transaction.

For the RaiAccept authentication, use the API credentials you generate in the Merchant portal.

Click to expand for the API info

 POST  https://authenticate.raiaccept.com

HEADERS
Key Value
Content-Type application/x-amz-json-1.1
X-Amz-Target AWSCognitoIdentityProviderService.InitiateAuth
PARAMETERS
Parameter and data type Required/
/optional		 Value Description
AuthFlow String Required USER_PASSWORD_AUTH
AuthParameters
USERNAME String Required Username (API credentials).
PASSWORD String Required Password (API credentials).
ClientID String Required kr2gs4117arvbnaperqff5dml 

{
"AuthFlow": "USER_PASSWORD_AUTH",
"AuthParameters": {
    "USERNAME": "1eab1b61-525f-45c5-97dc-1a57b01a1c14",
    "PASSWORD": "chMkiMwP%+1_c?Jl(4bg5Xs8WbN3(2-<)kB"
},
"ClientId": "kr2gs4117arvbnaperqff5dml"
}

200 OK
Response contains the following field: IdToken. Use the IdToken value as the authorization bearer token for the following API communication.
Negative responses
For the complete list of negative responses visit Amazon API reference.

2. Create order entry🔗︎

Create an order database entry with a unique order ID in the RaiAccept system.

RaiAccept API returns a response with all the original parameters and the additional parameters orderIdentification (the unique order ID), merchantAccountId and statementDescriptorShortVersion, which is the merchant identification the consumer will see in the RaiAccept payment form (you can customize this in the Merchant portal profile settings).

Click to expand for the API info

 POST  https://trapi.raiaccept.com/orders

HEADERS
Key Value
Authorization Bearer IdToken (from Authentication)
Content-Type application/json
PARAMETERS
Parameter and data type Required/
/optional		 Description
consumer Consumer’s details.
firstName String (0-32) Optional Only letters, hyphens, apostrophes, periods.
lastName String (0-32) Optional Only letters, hyphens, apostrophes, periods.
email String (0-255) Recommended Requires a valid email format (with @ symbol).
mobilePhone String (0-15) Recommended Accepts both +381 and 00381 formats, without spaces.
phone String (0-15) Optional Accepts both +381 and 00381 formats, without spaces.
workPhone String (0-15) Optional Accepts both +381 and 00381 formats, without spaces.
ipAddress String (0-255) Recommended
billingAddress Consumer’s billing address.
firstName String (0-32) Recommended Only letters, hyphens, apostrophes, periods.
lastName String (0-32) Recommended Only letters, hyphens, apostrophes, periods.
addressStreet1 String (0-50) Recommended Accepts letters, numbers, hyphens, apostrophes, periods, slashes, commas.
addressStreet2 String (0-50) Optional
addressStreet3 String (0-50) Optional
city String (0-50) Recommended Accepts letters, numbers, hyphens, apostrophes, periods, slashes, commas.
postalCode String (0-16) Recommended Only alphanumerical characters, hyphens.
country String-ENUM Recommended ISO 3166-1 alpha-3 country code.
State String (0-3) Optional Accepts letters, numbers, hyphens, apostrophes, periods, slashes, commas.
invoice
amount Number (more than 0) Required Total invoice amount.
currency String-ENUM Required ISO 4217 alphabetic currency code.
description String (0-200) Optional Order description.
merchantOrderReference
String (1-150)		 Required Merchant’s order number (e. g. from the e-commerce solution). Make sure you send a unique order number each time. Only alphanumeric characters, hyphens, and underscores allowed.
items
description String (0-100) Optional Item name.
numberOfItems Integer Required Number of items.
price Number (more than 0) Required Price of one item.
paymentMethodPreference String-ENUM Required The payment method to request for the checkout session. Supported values: CARD, GOOGLE_PAY, APPLE_PAY. Provide one value. When additional payment methods (such as Google Pay or Apple Pay) are enabled for your merchant account, they will automatically appear together with card payments during checkout.
allowedPaymentMethods Array of String-ENUM Optional Limits which wallet payment methods are available for this order. Supported values: APPLE_PAY, GOOGLE_PAY. For details, see the Control payment methods per order section.
shippingAddress Consumer’s shipping address.
firstName String (0-32) Recommended Only letters, hyphens, apostrophes, periods.
lastName String (0-32) Recommended Only letters, hyphens, apostrophes, periods.
addressStreet1 String (0-50) Recommended Accepts letters, numbers, hyphens, apostrophes, periods, slashes, commas.
addressStreet2 String (0-50) Optional
addressStreet3 String (0-50) Optional
city String (0-50) Recommended Accepts letters, numbers, hyphens, apostrophes, periods, slashes, commas.
postalCode String (0-16) Recommended Only alphanumerical characters, hyphens.
country String-ENUM Recommended ISO 3166-1 alpha-3 country code.
State String (0-3) Recommended Accepts letters, numbers, hyphens, apostrophes, periods, slashes, commas.
urls Frontend URLs (successUrl, cancelUrl, failUrl) define where the consumer is redirected after checkout. These redirects serve only the frontend flow and do not reflect the actual transaction result. To handle transaction status on the backend, use the notificationUrl webhook and then call the Retrieve order details endpoint to confirm the final order status.

Include the orderId as a URL parameter for tracking and personalization. All URLs must use the https:// prefix.
successUrl String (0-255) Required Frontend redirect after a successful transaction.
cancelUrl String (0-255) Required Frontend redirect if the consumer cancels the checkout process.
failUrl String (0-255) Required Frontend redirect if the transaction fails.
notificationUrl String (0-255) Optional Backend URL to receive webhook notifications on transaction status changes. Webhooks provide status updates but are not the final confirmation. For reliable verification of the final order status, call the Retrieve order details endpoint after receiving the webhook.
linkId String Optional ID of the payment link - if used.
recurring Parameters used to retrieve the consumer's previously saved payment card for one-click checkout.
cardToken String Optional Payment card token. Note that if you send both cardToken and customerReference, RaiAccept uses the Consumer flow.
customerReference String (0-64) Optional ID of the consumer in the Merchant's database. Only alphanumeric characters, hyphens, and underscores allowed.
recurringModel String Optional NONE if the transaction is a one-time purchase, ONE_CLICK_CHECKOUT if you are storing or retrieving payment cards. 

{
    "billingAddress": {
        "addressStreet1": "Resavska 1",
        "addressStreet2": "",
        "addressStreet3": "",
        "city": "Beograd",
        "country": "SRB",
        "firstName": "Milica",
        "lastName": "Petrovic",
        "postalCode": "11000",
        "state": ""
    },
    "consumer": {
        "email": "milica@petrovic.rs",
        "firstName": "Milica",
        "ipAddress": "",
        "lastName": "Petrovic",
        "mobilePhone": "+381113202100",
        "phone": "",
        "workPhone": ""
    },
    "invoice": {
        "amount": 4000,
        "currency": "RSD",
        "description": "Test Order",
        "items": [
            {
                "description": "ItemA",
                "numberOfItems": 1,
                "price": 4000
            }
        ],
        "merchantOrderReference": "12345678927"
    },
    "paymentMethodPreference": "CARD",
    "shippingAddress": {
        "addressStreet1": "Resavska 1",
        "addressStreet2": "",
        "addressStreet3": "",
        "city": "Beograd",
        "country": "SRB",
        "firstName": "Milica",
        "lastName": "Petrovic",
        "postalCode": "11000",
        "state": ""
    },
    "urls": {
        "cancelUrl": "https://yourshopname.rs/cancel/?orderId=1521348554419&headless=true",
        "failUrl": "https://yourshopname.rs/error/?orderId=1521348554419&headless=true",
        "notificationUrl": "https://webhook.site/cb7f55c6-e7aa-49dd-9d28-a22333cc1551",
        "successUrl": "https://yourshopname.rs/success/?orderId=1521348554419&headless=true"
    }
}
    "linkId": "string",
    "recurring": {
        "cardToken": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "customerReference": "string",
        "recurringModel": "NONE"
    }
}

orderIdentification Order ID to use to create checkout session.
merchant
merchantAccountId Merchant Account ID (as displayed in the Merchant portal).
statementDescriptorShortVersion Merchant name that will be displayed in the RaiAccept payment form.
isProduction If true, the request is made in the production environment and you authenticate with production API credentials. If false, the request is made in the Sandbox environment with Sandbox API credentials.
createdOn Date and time of creation of order in the format YYYY-MM-DDTHH:MM:SSZ, UTC time.
For all other response parameters, refer to the request parameters.

201 Order was created. 

{
"orderIdentification": "D-001-ORD-3833f9de-551c-443b-9034-279e73051ed1",
    "paymentMethodPreference": "CARD",
    "merchant": {
        "merchantAccountId": "D-001-MA-vGWWZLm4",
        "statementDescriptorShortVersion": "yourShopName"
    },
    "createdOn": "2022-09-14T16:20:07Z"
    "isProduction": true,
[…]
}
400 HTTP request message readingh or validation failed.
401 Authentication error.
403 MerchantAccountId is invalid or does not belong to this user.
404 HTTP request does not match any handler available by server or object not found.
405 Method not allowed.
406 Not acceptable.
409 Authentication error.
410 Authentication error.
415 Unsupported media type.
500 Internal server error or misconfiguration.

3. Create payment session🔗︎

Generate the URL of the payment form to display in the consumer’s browser.

When you generate the payment form URL, you can set the display language of the payment form. Visit Language prerequisites to learn more.

Click to expand for the API info

 POST  https://trapi.raiaccept.com/orders/orderIdentification/checkout

AUTHORIZATION
Bearer IdToken (from Authentication)
PARAMETERS
Use the same parameters and their values you used in step 2 Create order entry. 

"Authorization":"Bearer [IdToken]"
{
    "billingAddress": {
        "addressStreet1": "Resavska 1",
        "addressStreet2": "",
        "addressStreet3": "",
        "city": "Beograd",
        "country": "SRB",
        "firstName": "Milica",
        "lastName": "Petrovic",
        "postalCode": "11000",
        "state": ""
    },
    "consumer": {
        "email": "milica@petrovic.rs",
        "firstName": "Milica",
        "ipAddress": "",
        "lastName": "Petrovic",
        "mobilePhone": "+381113202100",
        "phone": "",
        "workPhone": ""
    },
    "invoice": {
        "amount": 4000,
        "currency": "RSD",
        "description": "Test Order",
        "items": [
            {
                "description": "ItemA",
                "numberOfItems": 1,
                "price": 4000
            }
        ],
        "merchantOrderReference": "{{MerchantOrderRef}}"
    },
    "paymentMethodPreference": "CARD",
    "shippingAddress": {
        "addressStreet1": "Resavska 1",
        "addressStreet2": "",
        "addressStreet3": "",
        "city": "Beograd",
        "country": "SRB",
        "firstName": "Milica",
        "lastName": "Petrovic",
        "postalCode": "11000",
        "state": ""
    },
    "urls": {
        "cancelUrl": "https://yourshopname.rs/cancel/?orderId=1521348554419&headless=true",
        "failUrl": "https://yourshopname.rs/error/?orderId=1521348554419&headless=true",
        "notificationUrl": "https://webhook.site/cb7f55c6-e7aa-49dd-9d28-a22333cc1551",
        "successUrl": "https://yourshopname.rs/success/?orderId=1521348554419&headless=true"
    }
    "linkId": "string",
    "recurring": {
        "cardToken": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "customerReference": "string",
        "recurringModel": "NONE"
    }
}

201 Session was created.
SessionId Payment form session ID.
isProduction If true, the request is made in the production environment and you authenticate with production API credentials. If false, the request is made in the Sandbox environment with Sandbox API credentials.
paymentRedirectURL URL of the payment form to display to the consumer.

201 Session was created. 

{
    "sessionId": "D-001-SESS-94c89598-7e41-4cf1-8d33-da262d69dde6",
    "paymentRedirectURL": "https://payment.raiaccept.com/checkout?paymentSession=D-001-SESS-94c89598-7e41-4cf1-8d33-da262d69dde6"
}
403 MerchantAccountId is invalid or does not belong to this user. 

{
    "errors": [
        {
        "fieldName": "string",
        "message": "string",
        "rejectedValue": "string"
        }
    ],
    "traceId": "string"
}
400 HTTP request message reading or validation failed.
401 Authentication error.
403 MerchantAccountId is invalid or does not belong to this user.
404 HTTP request does not match any handler available by server or object not found.
405 Method not allowed.
406 Not acceptable.
409 Authentication error.
410 Authentication error.
415 Unsupported media type.
500 Internal server error or misconfiguration.

Control payment methods per order🔗︎

RaiAccept lets you choose which payment methods (Apple Pay, Google Pay, and card payments, in any combination) should appear in the checkout page for each individual order. This gives you full control to adapt the payment experience to different devices, environments or user flows.

Click to expand for details

Use the optional allowedPaymentMethods field to limit which payment methods can be shown for a specific order:

  • works with Apple Pay, Google Pay and card payments
  • applies per order (you decide based on device, user, flow, etc.)
  • is optional and fully backward compatible

Note that CARD payment is always available and cannot be restricted.

Include allowedPaymentMethods in:

  • POST /orders
  • POST /orders/{orderIdentification}/checkout

RaiAccept uses this field to decide which wallet buttons to show for this order.

Supported values🔗︎

"allowedPaymentMethods": ["APPLE_PAY", "GOOGLE_PAY"]
  • APPLE_PAY
  • GOOGLE_PAY
  • CARD payment always allowed and does not need to be listed

Behavior overview🔗︎

Merchant settings allowedPaymentMethods sent What the consumer sees
Apple Pay + Google Pay enabled not sent Apple Pay + Google Pay + card
Apple Pay + Google Pay enabled ["APPLE_PAY"] Apple Pay + card
Apple Pay + Google Pay enabled [] (empty list) card only
Only Google Pay enabled ["APPLE_PAY"] Google Pay + card (Apple Pay is ignored)

Rules🔗︎

  • the field only restricts payment methods; it does not activate new ones
  • Apple Pay / Google Pay must be enabled in your Merchant portal
  • unsupported methods are ignored (the request does not fail)
  • empty list ([]) - only card payments for this order
  • field missing or null - all payment methods enabled in your Merchant portal are used

Typical usage examples🔗︎

  • device-based control (for example, Google Pay for Android, Apple Pay for iOS, card only for embedded browsers)
  • gradual rollout of a new wallet to a portion of orders
  • custom business rules (guest checkout, subscriptions, high-value orders, etc.)

Retrieve order details🔗︎

OPTIONAL | Returns the complete order details from RaiAccept for the specified RaiAccept order ID.

Click to expand for the API info

 GET  https://trapi.raiaccept.com/orders/orderIdentification

AUTHORIZATION
Bearer IdToken (from Authentication)
PARAMETERS
Send request without body.

PARAMETERS
Parameter Description
status Status of the order. Possible responses: DRAFT, CHECKOUT, PAID, PARTIALLY_REFUNDED, FULLY_REFUNDED, FAILED, CANCELED, ABANDONED.
For all other parameters, refer to request and response parameters in step 2 Create order entry .

200 Order data are returned. 

{
    "orderIdentification": "D-001-ORD-d94e7447-494e-43ad-a460-5cd94b3fb0d8",
    "paymentMethodPreference": "CARD",
    "merchant": {
        "merchantAccountId": "D-001-MA-vGWWZLm4",
        "statementDescriptorShortVersion": "yourShopName"
    },
    "createdOn": "2022-09-14T20:27:27Z",
    "consumer": {
        "firstName": "Milica",
        "lastName": "Petrovic",
        "email": "milica@petrovic.rs",
        "mobilePhone": "+381113202100",
        "phone": "",
        "workPhone": "",
        "ipAddress": ""
        },
    "invoice": {
        "merchantOrderReference": "1551764626669",
        "amount": 4000.00,
        "currency": "RSD",
        "description": "Test Order",
        "items": [
            {
                "numberOfItems": 1,
                "price": 4000.00,
                "description": "ItemA"
            }
        ]
    },
    "shippingAddress": {
        "firstName": "Milica",
        "lastName": "Petrovic",
        "addressStreet1": "Resavska 1",
        "addressStreet2": "",
        "addressStreet3": "",
        "postalCode": "11000",
        "city": "Beograd",
        "state": "",
        "country": "SRB"
    },
    "billingAddress": {
        "firstName": "Milica",
        "lastName": "Petrovic",
        "addressStreet1": "Resavska 1",
        "addressStreet2": "",
        "addressStreet3": "",
        "postalCode": "11000",
        "city": "Beograd",
        "state": "",
        "country": "SRB"
    },
    "callbackUrls": {
        "successUrl": " https://yourshopname.rs/success/?orderId=1521348554419&headless=true",
        "failUrl": " https://yourshopname.rs/error/?orderId=1521348554419&headless=true",
        "cancelUrl": " https://yourshopname.rs/cancel/?orderId=1521348554419&headless=true",
        "notificationUrl": "https://webhook.site/cb7f55c6-e7aa-49dd-9d28-a22333cc1551"
    },
    "isProduction": false
    "linkId": "string",
    "status": "DRAFT",
    "recurring": {
        "cardToken": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "customerReference": "string",
        "recurringModel": "NONE"
    }
}
400 HTTP request message reading or validation failed.
401 Authentication error.
403 MerchantAccountId is invalid or does not belong to this user.
404 HTTP request does not match any handler available by server or object not found.
405 Method not allowed.
406 Not acceptable.
409 Authentication error.
410 Authentication error.
415 Unsupported media type.
500 Internal server error or misconfiguration.

Retrieve all transactions for an order🔗︎

OPTIONAL | Returns all transactions and their details related to a RaiAccept order ID.

Click to expand for the API info

 POST  https://trapi.raiaccept.com/orders/orderIdentification/transactions

AUTHORIZATION
Bearer IdToken (from Authentication)
PARAMETERS
Send request without body.

200 Transaction data are returned.
transactionId RaiAccept ID of the transaction.
transactionAmount Purchase or refund amount.
transactionCurrency Transaction currency (ISO 4217 alphabetic currency code).
isProduction If true, the request is made in the production environment. If false, the request is made in the Sandbox environment./td>
transactionType PURCHASE or REFUND.
paymentMethod Selected payment method (CARD).
status Status of the transaction. Possible responses: DRAFT, PENDING, SUCCESS, FAILED.
statusCode Transaction response code.
statusMessage Success or Fail.
createdOn Date and time of the transaction creation.
updatedOn Date and time of the last transaction update.

200 Transaction data are returned. 

{
    "transactionId": "R-001-TX-ab2301a6-104c-436e-bf60-ccc0bc9d6ae2",
    "transactionAmount": 4000.00,
    "transactionCurrency": "RSD",
    "isProduction": false,
    "transactionType": "PURCHASE",
    "paymentMethod": "CARD",
    "status": "SUCCESS",
    "statusCode": "0000",
    "statusMessage": "Success",
    "createdOn": "2023-03-08T10:19:55Z",
    "updatedOn": "2023-03-08T10:19:56Z"
    "recurringType": "NONE"
}
403 Forbidden request. 

{
    "errors": [
        {
        "fieldName": "string",
        "message": "string",
        "rejectedValue": "string"
        }
    ],
    "traceId": "string"
}
400 HTTP request message reading or validation failed.
401 Authentication error.
403 MerchantAccountId is invalid or does not belong to this user.
404 HTTP request does not match any handler available by server or object not found.
405 Method not allowed.
406 Not acceptable.
409 Authentication error.
410 Authentication error.
415 Unsupported media type.
500 Internal server error or misconfiguration.

Retrieve transaction status🔗︎

OPTIONAL | Returns the transaction details and status from RaiAccept.

Click to expand for the API info

 GET  https://trapi.raiaccept.com/orders/OrderID/transactions/TransactionId

AUTHORIZATION
Bearer IdToken (from Authentication)
PARAMETERS
Send request without body.

PARAMETERS
Parameter Description
transaction
transactionId Unique RaiAccept transaction ID.
transactionAmount Total transaction amount.
transactionCurrency Transaction currency in ISO 4217 alphabetic currency code.
isProduction If true, the request is made in the production environment and you authenticate with production API credentials. If false, the request is made in the Sandbox environment with Sandbox API credentials.
transactionType Transaction type – PURCHASE or REFUND.
paymentMethod Payment type – fixed value CARD.
status Status of the transaction. Possible responses: DRAFT, PENDING, SUCCESS, FAILED.
statusCode In a case of a successful transaction, code 0000 is sent in the API response. For the complete list of error codes refer to Transaction responses and error codes.
statusMessage Description of the transaction result.
createdOn Date and time of creation of order in the format YYYY-MM-DDTHH:MM:SSZ, UTC time.
updatedOn Date and time of the last update of order in the format YYYY-MM-DDTHH:MM:SSZ, UTC time.
merchant Merchant details.
merchantAccountId Merchant Account ID (as displayed in the Merchant portal).
statementDescriptor
ShortVersion		 Merchant name that will be displayed in the RaiAccept payment form.
order Order details.
orderIdentification RaiAccept order ID.
invoice
merchantOrderReference Merchant’s order number (e. g. from the e-commerce solution).
description Order description.
recurring Parameters used to revoke the consumer's previously saved payment card for one-click checkout.
cardToken Tokenized version of the card number.
customerReference ID of the consumer in the Merchant's database.
recurringModel NONE if the transaction is a first-time purchase, ONE_CLICK_CHECKOUT if stored card was used.
card Payment card details.
maskedCardNumber Card number with masked digits.
cardHolderName Card holder's name.
type Card type, e.g. Visa or MasterCard.
issuerCountry Country where the card was issued.
cardToken Tokenized version of the card number.
cardSavingApproved If True, the consumer gave the consent to save the card number for later use.
expiryMonth Month of expiration of the card.
expiryYear Year of expiration of the card. 

{
"transaction": {
    "transactionId": "D-001-TX-ffa6c2b4-b1d7-431d-8452-ebf858b2b175",
    "transactionAmount": 2000.00,
    "transactionCurrency": "RSD",
    "isProduction": false,
    "transactionType": "REFUND",
    "paymentMethod": "CARD",
    "status": "SUCCESS",
    "statusCode": "0000",
    "statusMessage": "Success",
    "createdOn": "2023-01-05T10:00:18Z",
    "updatedOn": "2023-01-05T10:00:19Z"
},
"merchant": {
    "merchantAccountId": "D-001-MA-HfDqSZwd",
    "statementDescriptorShortVersion": "agrolivana"
},
"order": {
    "orderIdentification": "D-001-ORD-edf3e8b2-8b0e-404a-b55a-e6b3c2dd7780",
    "invoice": {
        "merchantOrderReference": "12345678922",
        "description": "Test Order"
    }
},
"card": {
    "maskedCardNumber": "512070******0019",
    "cardHolderName": "Milica Petrovic",
    "type": "MASTERCARD",
    "issuerCountry": "UKR",
     "cardToken": "0e46b504-c5c4-4072-a624-0aec4d8a39b7"
    }
}

Refund API resource🔗︎

You can issue refund from Merchant portal, from your shop system or via an API request. For more information about refunds, visit the Merchant portal chapter.

Info

You cannot refund the consumer more than the original transaction amount. The refund must be done in the same currency as the original transaction.

The issued refund is made to the original purchase payment method.

The order of API communication is as follows:

  1. Perform authentication and retrieve token
  2. Issue a refund for an order ID

1. Authentication🔗︎

RaiAccept uses Amazon Cognito service to verify the merchant’s credentials and to create an authentication token to use in the transaction.

For the RaiAccept authentication, use the API credentials you generate in the Merchant portal.

Click to expand for the API info

 POST  https://authenticate.raiaccept.com

HEADERS
Key Value
Content-Type application/x-amz-json-1.1
X-Amz-Target AWSCognitoIdentityProviderService.InitiateAuth
PARAMETERS
Parameter and data type Required/
/optional		 Value Description
AuthFlow String Required USER_PASSWORD_AUTH
AuthParameters
USERNAME String Required Username (API credentials).
PASSWORD String Required Password (API credentials).
ClientID String Required kr2gs4117arvbnaperqff5dml 

{
"AuthFlow": "USER_PASSWORD_AUTH",
"AuthParameters": {
    "USERNAME": "1eab1b61-525f-45c5-97dc-1a57b01a1c14",
    "PASSWORD": "chMkiMwP%+1_c?Jl(4bg5Xs8WbN3(2-<)kB"
},
"ClientId": "kr2gs4117arvbnaperqff5dml"
}

200 OK
Response contains the following field: IdToken. Use the IdToken value as the authorization bearer token for the following API communication.
Negative responses
For the complete list of negative responses visit Amazon API reference.

2. Issue a refund🔗︎

Issues the refund. Refund is referenced in RaiAccept to the purchase OrderID and TransactionId. You may issue a partial or a complete (full) refund.

Click to expand for the API info

 POST  https://trapi.raiaccept.com/orders/OrderID/transactions/TransactionId/refund

AUTHORIZATION
Bearer IdToken (from Authentication)
PARAMETERS
Parameter and data type Required/
/optional		 Description
amount Number (more than 0) Required Refund amount. Must not exceed the original purchase amount.
currency String Required Refund currency. Use the same currency as the original transaction. 

{
    "amount": 4000,
    "currency": "RSD"
}

transactionId ID of the successful refund transaction. 

{
    "transactionId": "D-001-TX-beab6179-f357-477d-ac7d-3e8b41100a65"
}

Retrieve refund status🔗︎

OPTIONAL | Retrieves the refund (transaction) details and status from RaiAccept.

Click to expand for the API info

 GET  https://trapi.raiaccept.com/orders/OrderID/transactions/TransactionId

AUTHORIZATION
Bearer IdToken (from Authentication)
PARAMETERS
Send request without body.

PARAMETERS
Parameter Description
transaction
transactionId Unique RaiAccept transaction ID.
transactionAmount Total transaction amount.
transactionCurrency Transaction currency in ISO 4217 alphabetic currency code.
isProduction If true, the request is made in the production environment and you authenticate with production API credentials. If false, the request is made in the Sandbox environment with Sandbox API credentials.
transactionType Transaction type – PURCHASE or REFUND.
paymentMethod Payment type – fixed value CARD.
status Status of the transaction. Possible responses: DRAFT, PENDING, SUCCESS, FAILED.
statusCode In a case of a successful transaction, code 0000 is sent in the API response. For the complete list of error codes refer to Transaction responses and error codes.
statusMessage Description of the transaction result.
createdOn Date and time of creation of order in the format YYYY-MM-DDTHH:MM:SSZ, UTC time.
updatedOn Date and time of the last update of order in the format YYYY-MM-DDTHH:MM:SSZ, UTC time.
merchant Merchant details.
merchantAccountId Merchant Account ID (as displayed in the Merchant portal).
statementDescriptor
ShortVersion		 Merchant name that will be displayed in the RaiAccept payment form.
order Order details.
orderIdentification RaiAccept order ID.
invoice
merchantOrderReference Merchant’s order number (e. g. from the e-commerce solution).
description Order description.
recurring Parameters used to revoke the consumer's previously saved payment card for one-click checkout.
cardToken Tokenized version of the card number.
customerReference ID of the consumer in the Merchant's database.
recurringModel NONE if the transaction is a first-time purchase, ONE_CLICK_CHECKOUT if stored card was used.
card Payment card details.
maskedCardNumber Card number with masked digits.
cardHolderName Card holder's name.
type Card type, e.g. Visa or MasterCard.
issuerCountry Country where the card was issued.
cardToken Tokenized version of the card number.
cardSavingApproved If True, the consumer gave the consent to save the card number for later use.
expiryMonth Month of expiration of the card.
expiryYear Year of expiration of the card. 

{
"transaction": {
    "transactionId": "D-001-TX-ffa6c2b4-b1d7-431d-8452-ebf858b2b175",
    "transactionAmount": 2000.00,
    "transactionCurrency": "RSD",
    "isProduction": false,
    "transactionType": "REFUND",
    "paymentMethod": "CARD",
    "status": "SUCCESS",
    "statusCode": "0000",
    "statusMessage": "Success",
    "createdOn": "2023-01-05T10:00:18Z",
    "updatedOn": "2023-01-05T10:00:19Z"
},
"merchant": {
    "merchantAccountId": "D-001-MA-HfDqSZwd",
    "statementDescriptorShortVersion": "agrolivana"
},
"order": {
    "orderIdentification": "D-001-ORD-edf3e8b2-8b0e-404a-b55a-e6b3c2dd7780",
    "invoice": {
        "merchantOrderReference": "12345678922",
        "description": "Test Order"
    }
},
"card": {
    "maskedCardNumber": "512070******0019",
    "cardHolderName": "Milica Petrovic",
    "type": "MASTERCARD",
    "issuerCountry": "UKR",
     "cardToken": "0e46b504-c5c4-4072-a624-0aec4d8a39b7"
    }
}

Payment form integration🔗︎

Payment form with close (X) icon

Payment form with the close (X) icon for cancelling the transaction (see note below)

Choose one of the following options to display the payment form to the customer.

Iframe window🔗︎

Display the payment form in an iframe window you embed on your e-commerce solution page. When the payment is completed, the window will display the success (or failure) URL you specified in your API request, for example, a confirmation of purchase. The consumer will not leave your e-commerce solution.

Recommended iframe window dimensions – frameless mode

  • Mobile: minimum 360 x 880 (responsive)
  • Desktop: minimum 640 x 780 (responsive)

Iframe frameless mode

By default, the payment form is displayed with a frame that includes a close icon (X) in the top-right corner. When the consumer clicks this icon, they are redirected to the cancelUrl.

When you use the iframe option, this is not necessary as the consumer never leaves your e-commerce solution. That means you can display a smaller window without the frame. To do this, when you display the iframe window, add the parameter mode=frameless to the end of the payment form URL provided by the Create payment form session API response, for example: https://payment.raiaccept.com/checkout?paymentSession=D-001-SESS-94c89598-7e41-4cf1-8d33-da262d69dde6&mode=frameless

We recommend to display the window with the frame when you use the redirect or new tab options, so that the consumer can return to your e-commerce solution in one click.

Iframe to parent communication

The iframe to parent communication can be used for custom integration: like displaying and hiding iframe inside merchant page or handling unexpect errors.

Iframe sends message via JavaScript postMessage to communicate the order payment result to parent page. The parent page can handle these message via listning JavaScript events window.addEventListener("message", messageHandlerFn).

type OrderResult = {
    name: "orderResult",
    payload: {
      status: "success" | "failure" | "cancel" | "exception",
      orderIdentification?: string,
      errorMessage?: string
    }
}
  • success: Order payment was succesfull. The iframe is redirected to successUrl defined in the order.
  • failure: Order payment was not succesfull. The iframe is redirected to failureUrl defined in the order.
  • cancel: Order payment was cancelled. The iframe is redirected to cancelUrl defined in the order.
  • exception: An exception occured and checkout process cannot proceed. It might be one of the following situations:
    • Payment session is expired or is not active. The iframe is redirected to failureUrl defined in the order.
    • An unexpect error occured during order payment. The iframe displays an error and cannot be redirected back to the merchant.
    • The exception is an edge case and is not supposed to occur frequently. If merchants want to react to this state, they should handle these cases on their own.

Full page as a redirect🔗︎

Redirect the consumer to a page with the payment form. When the payment is completed, consumer will be automatically redirected to the success (or failure) URL, for example, back to your e-commerce solution.

Full page as a new tab🔗︎

Open the payment form in new tab. When the payment is completed, consumer will be automatically redirected to the success (or failure) URL.

Notification webhook🔗︎

When the consumer completes their transaction, and when you issue a refund, RaiAccept can send a notification webhook about the transaction result. Specify your endpoint to receive webhooks as notificationUrl in the Create order entry API request.

To test the payment result notification feature, you can use Webhook.site or any other similar online tool. When you click the link, a new URL is generated that can receive and display HTTP requests.

After your system receives a webhook notification, it should call the Retrieve order details endpoint to verify the final order status and continue processing the order in your backend.

If your infrastructure uses IP allowlisting or firewall restrictions, make sure to allow incoming webhook requests from the following RaiAccept IP range: 18.96.33.128/29

Webhook delivery

If your endpoint does not respond successfully (for example due to a timeout or temporary issue), RaiAccept will retry delivering the notification up to three times.

These retries occur within a short time window, typically completed within several seconds of the initial attempt.

Your system should be able to handle receiving the same notification more than once and always verify the final order status using the API.

Click to expand the notification webhook details

PARAMETERS
Parameter Description
transaction
transactionId Unique RaiAccept transaction ID.
transactionAmount Total transaction amount.
transactionCurrency Transaction currency in ISO 4217 alphabetic currency code.
isProduction If true, the request is made in the production environment and you authenticate with production API credentials. If false, the request is made in the Sandbox environment with Sandbox API credentials.
transactionType Transaction type – PURCHASE or REFUND.
paymentMethod Payment type – fixed value CARD.
status Transaction status.
statusCode In a case of a successful transaction, code 0000 is sent in the webhook. For the complete list of error codes refer to Transaction responses and error codes.
statusMessage Description of the transaction result.
createdOn Date and time of creation of order in the format YYYY-MM-DDTHH:MM:SSZ, UTC time.
updatedOn Date and time of the last update of order in the format YYYY-MM-DDTHH:MM:SSZ, UTC time.
merchant Merchant details.
merchantAccountId Merchant Account ID (as displayed in the Merchant portal).
statementDescriptor
ShortVersion		 Merchant name that will be displayed in the RaiAccept payment form.
order Order details.
orderIdentification RaiAccept order ID.
preferredPaymentMethod Payment type – fixed value CARD.
invoice Invoice details.
merchantOrder
Reference		 Merchant’s order number (e. g. from the e-commerce solution).
description Order description.
items Item details
numberOfItems Number of items.
price Price for one item.
description Item name.
consumer Consumer’s details.
firstName
lastName
email
mobilePhone
phone
workPhone
ipAddress
billingAddress Consumer’s billing address.
firstName
lastName
addressStreet1
addressStreet2
addressStreet3
postalCode
city
State
country ISO 3166-1 alpha-3 country code.
shippingAddress Consumer’s shipping address.
firstName
lastName
addressStreet1
addressStreet2
addressStreet3
postalCode
city
State
country ISO 3166-1 alpha-3 country code.
card Card details.
maskedCardNumber Card number with masked digits.
cardHolderName Card holder's name.
type Card type, e.g. Visa or MasterCard.
issuerCountry Country where the card was issued.
cardToken Tokenized version of the card number.
callbackUrls URLs to redirect the consumer to.
successUrl URL to redirect the consumer in case of a successful transaction.
failUrl URL to redirect the consumer in case of a unsuccessful transaction.
cancelUrl URL to redirect the consumer in case the transaction is cancelled.
notificationUrl URL to receive the webhook notification. 

{
  "transaction": {
    "transactionId": "R-001-TX-ab2301a6-104c-436e-bf60-ccc0bc9d6ae2",
    "transactionAmount": 4000,
    "transactionCurrency": "RSD",
    "isProduction": false,
    "transactionType": "PURCHASE",
    "paymentMethod": "CARD",
    "status": "SUCCESS",
    "statusCode": "0000",
    "statusMessage": "Success",
    "createdOn": "2023-03-08T10:19:55Z",
    "updatedOn": "2023-03-08T10:19:56Z"
  },
  "merchant": {
    "merchantAccountId": "D-001-MA-QkoC2XyB",
    "statementDescriptorShortVersion": ""
  },
  "order": {
    "orderIdentification": "R-001-ORD-d68b0e14-66c0-4a89-940a-9438cf5e2e57",
    "preferredPaymentMethod": "CARD",
    "invoice": {
      "merchantOrderReference": "12345678940",
      "description": "Test Order",
      "items": [
        {
          "numberOfItems": 1,
          "price": 4000,
          "description": "ItemA"
        }
      ]
    },
    "consumer": {
      "firstName": "Milica",
      "lastName": "Petrovic",
      "email": "milica@petrovic.rs",
      "mobilePhone": "+381113202100",
      "phone": "",
      "workPhone": "",
      "ipAddress": ""
    },
    "billingAddress": {
      "firstName": "Milica",
      "lastName": "Petrovic",
      "addressStreet1": "Resavska 1",
      "addressStreet2": "",
      "addressStreet3": "",
      "postalCode": "11000",
      "city": "Beograd",
      "state": "",
      "country": "SRB"
    },
    "shippingAddress": {
      "firstName": "Milica",
      "lastName": "Petrovic",
      "addressStreet1": "Resavska 1",
      "addressStreet2": "",
      "addressStreet3": "",
      "postalCode": "11000",
      "city": "Beograd",
      "state": "",
      "country": "SRB"
    }
  },
  "card": {
    "maskedCardNumber": "499999******0011",
    "cardHolderName": "Jane Doe",
    "type": "VISA",
    "issuerCountry": "UKR",
    "cardToken": "0e46b504-c5c4-4072-a624-0aec4d8a39b7"
  },
  "callbackUrls": {
    "successUrl": "https://yourshopname.rs/success/?orderId=1521348554419&headless=true",
    "failUrl": "https://yourshopname.rs/error/?orderId=1521348554419&headless=true",
    "cancelUrl": "https://yourshopname.rs/cancel/?orderId=1521348554419&headless=true",
    "notificationUrl": "https://webhook.site/8f8595c7-3469-4bfa-88ee-99f103b0a049"
  }
}

Transaction responses and error codes🔗︎

RaiAccept API supports the standard HTTP responses and error codes. Additionally, RaiAccept sends the following 4-digit response codes in the notification webhook.

Click to expand the list of responses and their explanations
Code Description
0000 Transaction successful.
1001 Decline by Issuer: The card issuer suspects the transaction to be fraudulent and therefore refuses.
1002 Decline by Issuer: The card issuer indicates an issue with the card and requests contact from the consumer.
1003 The card issuer indicates an issue with the card and requests contact from the consumer. The consumer can use another payment method. Alternatively, the consumer can try again after they resolve the issue with their bank.
1004 Decline by Issuer: The transaction is not permitted. Either a restriction is applied by the Issuer to the cardholder, or the transaction is not permitted by law.
1005 Decline by Issuer: The card is reported as lost and therefore cannot be accepted. Consumer is advised to try again using a different payment method.
1006 Decline by Issuer: The card is reported as stolen and therefore cannot be accepted. Consumer is advised to try again using a different payment method.
1007 The transaction is identified as a duplicate and therefore is not processed. Verify that the transaction elements (like the merchantOrderReference field) you send are unique or contact support.
1008 The original referencing transaction is missing or is invalid. Reattempt only after you provide a correct referencing transaction or contact support.
1009 The selected currency is not supported for the Merchant and therefore the transaction cannot be processed.
2001 Restricted Card: The card issuer restricts where the card can be used. For example, because of embargoes.
2002 Invalid Merchant ID: Either a wrong merchant account is sent, merchant values are wrong when running the 3-D Secure flow, the web service used isn't permitted for that merchantAccountId, or the company is not active.
2003 The transaction amount is specified in an invalid format. For example, an invalid character such as a dollar sign or a space is used. Consumer should correct or use another payment method.
2004 Insufficient funds in the consumer’s account. Consumer can try again after they add funds to their bank account or use another payment method.
2005 The credited amount exceeds the amount of the referenced debit transaction.
2006 The consumer fails to perform the 3-D Secure Authentication successfully. The consumer is advised to try again.
2007 The 3-D Secure authentication fails because of an unknown device. The consumer is advised to try again later or use a different payment method.
2008 The 3-D Secure authentication fails because of an unsupported device. The consumer is advised to try again later or use a different payment method.
2009 The 3-D Secure Authentication Fequency Limit of this card is exceeded and therefore the issuing bank cannot accept the transaction. The consumer is advised to use a different payment method or contact the issuing bank.
2010 The 3-D Secure authentication cannot be performed because no card records exist in 3-D Secure Access Control Server of the Issuer Bank. The consumer is advised to use a different payment method.
2011 The 3-D Secure authentication results into a security failure. The consumer is advised to use a different payment method.
2012 The 3-D Secure authentication cannot be performed because the customers card is not enrolled. The consumer is advised to contact their issuing bank or use a different payment method.
2013 The transaction was declined by the Issuer because the maximum number of challenges is exceeded. The consumer is advised to contact their issuing bank or try a different payment method.
2014 The Non Payment Authentication (NPA) transaction is declined by the issuer because it is not supported. Please make sure that the correct 3-D Secure data are provided in the transaction, otherwise contact support.
2015 The Merchant Initiated Authentication (3RI) transaction was declined by the issuer because it is not supported. Please make sure that the correct 3-D Secure data are provided in the transaction, otherwise contact support.
2016 The Issuer Bank´s Access Control Server responsible for 3-D Secure, cannot be reached at all. The consumer is advised to try again later or use a different payment method.
2017 The Issuer bank is expecting a Decoupled 3-D Secure Authentication. Please make sure that the correct 3-D Secure data are provided in the transaction, otherwise contact support.
2018 The transaction was declined by the Issuer because the Decoupled Authentication was not performed within expected time. The consumer is advised to try again later or use different payment method.
2019 The transaction was declined by the Issuer because insufficient time was provided to the consumer to perform the Decoupled Authentication. Please contact support.
2020 The transaction was declined by the Issuer because the 3-D Secure authentication was attempted but not performed by the consumer.
2021 The Issuer Bank´s Access Control Server responsible for 3-D Secure, cannot be reached in timely fashion. The consumer was advised to try again later or use a different payment method.
2022 Transaction declined by Issuer due to daily or monthly limits on transaction amount or count being exceeded. The consumer was advised to remove or increase any limits, use a different payment method or to contact the Issuing Bank for further instructions.
3001 Strong Customer Authentication is required for the transaction. If the transaction is in scope of PSD2 and did not go through 3-D Secure, retry with 3-D Secure. This is also referred to as a "Soft Decline".
3002 Decline by Issuer: The consumer is using an expired card.
3003 The card issuer is unable to validate the card/account number, possibly because an invalid character was used, or the card is not supported by the processor.
3004 The consumer either provides an expired card or the expiration date is invalid. Consumer is advised to use a valid expiry date or to try a different payment method.
3005 The consumer provides an incorrect CVV. Consumer is advised to use the correct CVV or to try different payment method.
3006 RaiAccept is unable to process the transaction due to a technical error with its processor.
3007 RaiAccept is unable to process the transaction due to a technical error with the payment schemes.
3008 The 3-D Secure authentication cannot be performed because of invalid 3-D Secure transaction. Please make sure that the recommended 3-D Secure data are provided in the transaction otherwise contact support.
3009 Decline by Issuer: Low confidence on suspected risk. The consumer is advised to contact their Issuer bank.
3010 Decline by Issuer: Medium confidence on suspected risk. The consumer is advised to contact their Issuer bank.
3011 Decline by Issuer: High confidence on suspected risk. The consumer is advised to contact their Issuer bank.
3012 Decline by Issuer: Very high confidence on suspected risk. The consumer is advised to contact their Issuer bank.
3013 Decline by Issuer: The preferred authentication method is not supported. Please make sure that the correct 3-D Secure data are provided in the transaction, otherwise contact support.
3014 Decline by Issuer: The validation of the Content Security Policy fails. Please make sure that the correct 3-D Secure data are provided in the transaction, otherwise contact support.
3015 Unfortunately the transaction cannot be processed because the Issuing Bank was invalid or not known. The consumer is advised to try again using a different payment method.
3016 Unfortunately the transaction cannot be processed because the Issuing Bank cannot be reached. The consumer is advised to try again using a different payment method.
3017 The transaction was declined by the Issuer due to a possible security issue with this card. The consumer is advised verify correctness of CVV. Alternatively, they can use another payment method or address the issue with their Issuing Bank.
4001 Generic refusal from the card issuer that has several possible causes.
5001 There are too many transaction retries within one session.
5002 This transaction is not permitted to cardholder. There is a risk-related rule that prevents the transaction from being completed.
6001 The transaction cannot be inserted into the batch file for triggering capture.
6002 There is no batch response file corresponding to the batch request for capture.
6003 The number of transactions in the batch response file does not match the number of transactions in the corresponding batch request file for capture.
6004 Identifier Field Missing – an important field or identifier (for example, trace_id or n-file name) is missing when trying to process the batch file and retrieve a transaction from database.
6005 An unknown error was reported for the transaction during batch processing.
6006 A duplicate of the batch file was sent to the processor to capture the transaction.
6007 A duplicate of this transaction was sent to the processor in the batch file to Capture the transaction.
6008 Technical error with the 3DS processing.
6009 Technical error in Risk module.
7001 The refund cannot be processed by RaiAccept because of invalid data. 
7002 The provided response from processor is missing business data critical to continue with the transaction.
7003 The transaction was not processed due to technical error connected to Tokenizer service. The consumer can try again shortly.
7004 There was a technical error and the transaction was not processed. The consumer can try again shortly.
7005 There was data validation error and the transaction cannot be processed. The consumer can try again shortly.
7006 The transaction cannot be processed within the expected time and is therefore cancelled by the Gateway. The consumer is not charged and can try again shortly.
7007 The reversal request encounters a technical error. 
7008 Authentication is declined by the 3DS router.
7009 The card brand is not supported for you or your acquirer bank.
7010 There was a technical infrastructure error. The consumer account was not charged, but they can try again shortly.
7011 There was a technical error while communication with processor. The consumer account was not charged, but they can try again shortly.
9999 The transaction was not processed due to an unknown technical error. Please contact support.