Zinia API Integration Guide

JANUARY 2023 RELEASE

Table of Contents
1 Introduction ............................................................................................................................................ 3
2 Getting Started ........................................................................................................................................ 5
2.1 The Basics ........................................................................................................................................... 5
2.2 Authentication .................................................................................................................................... 5
2.3 Data Formats ...................................................................................................................................... 6
2.4 HTTP Status Codes & Errors................................................................................................................ 7
2.4.1 Convention ................................................................................................................................ 7
2.4.2 List of Status Codes ................................................................................................................... 7
2.5 Zinia Use Cases ................................................................................................................................... 9
2.5.1 Web Link-Up Process................................................................................................................. 9
2.5.2 Link-Up via API with OTP (Work In Progress) ............................................................................ 9
2.5.3 Link-Up via API without OTP ................................................................................................... 11
2.6 Order Status Overview ..................................................................................................................... 11
3 Zinia APIs ............................................................................................................................................... 14
3.1 Zinia Merchant Security.................................................................................................................... 14
3.1.1 Login ........................................................................................................................................ 14
3.2 Zinia Checkout API ............................................................................................................................ 16
3.2.1 Create Checkout Order ........................................................................................................... 16
3.2.2 Retrieve Risk Data ................................................................................................................... 26
3.2.3 Retrieve Customer Legal Checks ............................................................................................. 29
3.2.4 Retrieve Payment Option Quotes ........................................................................................... 36
3.3 Zinia Link-Up API (Work In Progress) ................................................................................................ 41
3.3.1 Submit Order ........................................................................................................................... 42
3.3.2 Confirm Order ......................................................................................................................... 42
3.4 Zinia Orders API ................................................................................................................................ 42
3.4.1 Create Order ........................................................................................................................... 42
3.4.2 Order Capture (Fully/Partially) ................................................................................................ 55
3.4.3 Cancel Order (Fully/Partially) .................................................................................................. 61
3.4.4 Refund Order (Fully/Partially) ................................................................................................. 66
4 Zinia Notification Process ...................................................................................................................... 72
4.1 Overview .......................................................................................................................................... 72
4.2 Which Events Are Notified?.............................................................................................................. 72
4.3 How Should You Manage Notifications? .......................................................................................... 74
4.4 Validating Notifications .................................................................................................................... 74
4.5 Notification Structure (Request Body) ............................................................................................. 75

1
5 Daily Settlement & Reporting ............................................................................................................... 77

2
1 Introduction
Zinia APIs have been designed to facilitate integration with e-commerce platforms in a quick and easy way.
This document sets out the integration flow and all the API documentation required to carry out the
integration using just a few lines of code.
All the information needed to integrate your e-commerce shop with the Zinia BNPL payment method can
be found in this document.
Follow these four simple steps to carry out the Zinia integration process:
1. Create an account with Zinia and request your test credentials.
Please contact our Merchant IT Support ([email protected]) and provide it with the
following details:
• Contact person, email address and other contact details
• Full business name
• E-commerce brand name
• E-commerce URL
• Short shop description
We will set up a specific SANDBOX environment for you to test your shop integration and provide
you with the Test API Credentials, which comprise:
• Client ID: Unique username that identifies your store.
• Client Secret: String associated with your Client ID and used to authorise access to our APIs
(password).
• Merchant API Key: Key that allows you to subscribe to and use our APIs.
We will also provide you with another set of credentials for the production environment.
• Should you decide to interact with Zinia through a payment gateway, an API Key will be shared
with the gateway that will need to be used in conjunction with your credentials.

2. Log into Zinia and generate your ApiKey.

Follow these steps during the authentication process:
a. Use the Zinia Merchant Security API (POST /cf-api-
auth/authentication/merchant/login) to retrieve your “accessToken” using your
credentials (Client ID and Client Secret).
b. Generate your “ApiKey” by encrypting the string “MerchantApiKey#accessToken” using
“publicKey” and the RSA-OAEP-256 algorithm. Finally, encode the resulting string to Base64
format.
c. This information should be included in the headers of all the requests sent to the Zinia
Checkout and Order APIs:
i. Authorization: Bearer <accessToken>
ii. ApiKey: <ApiKey>

3. Integrate with the Zinia BNPL payment method at checkout by calling the Zinia Checkout API (POST
/checkout/orders). The Checkout API will provide a URL to show users the Zinia checkout payment
screen (customer Link-Up process) to consolidate the order.

3
 Customer at ecommerce Ecommerce. captures
selects products filling basket additional information
Merchant
Merchant
Product Catalog Add Customer Zinia Merchant
Data: BNPL Payment Sale
TV 1 … Phone? Page Confirmation
TV 2 … Email?
TV 3 … Shipping Address
Billing Address
Shop BUY
…
Customer

/v1/Order API

There is also an option to directly create an order in Zinia without the customer having to go through
the Link-Up process. This is carried out by calling the Zinia Link-Up API (POST /link-up/orders
and POST /link-up/orders/{orderId}/confirm).

4. Integrate your store’s order management shipment and refund system with the Zinia Orders API for
cancellations (POST /order-management/orders/{orderId}/cancellations), shipment
confirmation (POST / order-management/orders/{orderId}/captures) and refunds (POST /
order-management/orders/{orderId}/refunds).

Merchant
Warehouse
shipment
User receives
package at
home

/v1/orders/{orderId}/captures

4
2 Getting Started

2.1 The Basics

The Zinia payment gateway is structured around REST APIs. Our APIs have predictable resource-oriented
URLs, accept JSON request bodies, return JSON-encoded responses and use standard HTTP response codes,
authentication and verbs.
You can use our API in test mode, which does not affect your live data or interact with banking networks.
The API keys and the URL you use for authentication and the request, respectively, determine whether the
request is made in live mode or test mode.

2.2 Authentication
To authenticate with Zinia, you need to use your API credentials and OAuth 2.0.
To receive both your live and test API credentials contact Merchant IT Support ([email protected]).
The API credentials consist of three elements:
• Client ID: Unique username that identifies your store.
example: merchant-username-example

• Client Secret: String associated with your Client ID and used to authorise access to our APIs (Password).
example: a4b8f2170a163d0f64fe7fbe74d0f1976ff90d67196c6620cda21a9c0e4d

• Merchant API Key: Key that allows you to subscribe to and use our APIs.
example: Bbmf9fm0gr83x19UK6a1kSwQFX333R9p

The above credentials will be used to obtain your “accessToken” and “ApiKey”:
• accessToken: Use the Zinia Merchant Security API (POST /cf-api-
auth/authentication/merchant/login).
The accessToken will last for a limited period of time. The expiration information is contained in the
response of this endpoint within the attribute "expiresIn".
All API requests require an access token, but you can use the same access token in all API calls while it
is valid. When it expires, another one will have to be requested.
example: 5X5zC840w27MOapfMbnv22iYkezNH3MeHBKwhJtEjBo=

• ApiKey: To generate yours, encrypt the string “MerchantApiKey#accessToken” using the “publicKey”
and RSA-OAEP-256 algorithm. Finally, encode the resulting string to Base64 format.
example: 5810f3dfffd6497db63b8764ba42c4407f6efded

This information should be sent in the header of every API request:

• Authorization: Bearer <accessToken>
• ApiKey: <ApiKey>
If the credentials are missing or wrong, the Zinia API will respond with a “401 Unauthorised” message.

5
2.3 Data Formats
In the endpoint description, each parameter type (string, number, DateTime, etc.) is described.
Furthermore, a standardised format is used for the following data across all Zinia APIs.
Please note that any rule stated in the description of a specific parameter overrides the general rules
explained in this section.

• Currency
We use the Alpha-3 currency code established in the ISO-4217 standard for defining currencies.
Examples: EUR, GBP or USD.

• Country
Countries are expressed using the Alpha-2 country codes established in the ISO-3166 standard.
Examples: NL for the Netherlands, GB for Great Britain and ES for Spain.

• Dates
Dates are expressed according to the ISO 8601 standard with combined date, time and time zone: YYYY-
MM-DDThh:mm[:ss[.nnn]]Z (24-hour format).
Example: 2021-12-23T12:34:56Z
An exception to this is the dates of birth field, where values are accepted in the YYYY-MM-DD format.
Example: 1980-11-15

• Language
Languages are expressed using a composition of language and country codes expressed as ll-LL, where:
o ll: Language Code: Two lowercase alphanumeric positions as per ISO 639-1.
o LL: Country Code: Two uppercase alphanumeric positions as per ISO 3166-1 Alpha-2.
Examples: en-GB, nl-NL or es-ES.

• Strings
Strings usually have a character limit. Please see the specification of each endpoint to find out more about
a particular field.

• Amount
Amounts should be sent as decimal-number values with 2-digit precision.
Examples: 43.56 for €43.56

• Encoding
All data sent to the Zinia APIs must be UTF-8 encoded.

6
2.4 HTTP Status Codes & Errors

2.4.1 Convention
Our API uses the general HTTP response status codes, mainly 2xx (successful), 4xx (client error) and 5xx
(server error) codes.
Our error messages in the response body will always appear in the following format:

• For all 4xx & 5xx errors:

{
"description": "<description>",
"errorCode": "<code>"
}

2.4.2 List of Status Codes

• 200 - OK
This status confirms that your HTTP request has been received and processed successfully. You will usually
get this status for the login request or when retrieving information for the Checkout Webpage.
In the Response Body you will find the information regarding your request.
{
"accessToken": "<your_access_token>",
"expiresIn": 1199,
"tokenType": "bearer"
}

• 201 - Created
This status confirms that your HTTP request has been received and that the resource has been created
successfully. You will usually get this status for any order creation, capture (shipping goods), cancellation or
refund request.
{
"resourceId": "<order/capture/cancellation/refund_id>"
}

• 204 – No Content
This status indicates that the server has successfully fulfilled the request and that there is no additional
content to be sent in the response payload body. You could get this status when trying to retrieve
information for the Checkout webpage using the wrong search criteria in the request.
In this case, there is no Response Body.

• 400 - Bad Request

The request body is missing or something is wrong with its structure.
{
"description": " Bad Request, please review it and try again",
"errorCode": "BAD_REQUEST"
}
Most endpoints have been devised to provide a description of the error in the corresponding field:
{

7
 "description": " field:[amount], rejected value:[566.700]",
"errorCode": "BAD_REQUEST"
}

• 401 - Unauthorised
The access token is missing or invalid, or you are trying to log in using invalid credentials.
{
"description": " Unauthorized!",
"errorCode": "UNAUTHORIZED"
}
When the request is not authorised, a HTML response may also appear:
<head><title>401 Authorization Required</title></head>
<body>
<center><h1>401 Authorization Required</h1></center>
<hr><center>openresty/1.21.4.1</center>
</body>
</html>

• 403 - Forbidden
This would appear if your token does not have the rights required, e.g., if you try to capture (ship), cancel or
refund a transaction that belongs to another account/business.
{
"description": " Operation cannot be executed",
"errorCode": "FORBIDDEN"
}

• 404 - Not found

This error code would usually appear if you were trying to make a capture (shipping goods), cancellation or
refund request with the wrong order identifier.
{
"description": " The resource requested could not be found",
"errorCode": "NOT_FOUND"
}

• 409 - Conflict
If the same capture, cancellation or refund request is sent twice within a 5-minute period, the second
repeated request will not be processed and this error message will appear.
{
"description": " Concurrent capture/cancellation/refund error",
"errorCode": "CONFLICT"
}

• 412 - Precondition failed and 422 - Unprocessable entity

These error codes indicate that the request could not be completed due to a failure in validating a
precondition or business rule. This may happen if you are trying to refund an item that has not yet been
shipped.
{
"description": " Precondition Failed",
"errorCode": "PRECONDITION_FAILED"
}

{
"description": " Unprocessable Entity",
8
 "errorCode": "UNPROCESSABLE_ENTITY"
}

• 500 - Server Error

This would appear if something went wrong regarding Zinia or any of its partners.
{
"description": " An error occurred, please try again later",
"errorCode": "GENERIC_ERROR"
}

2.5 Zinia Use Cases

2.5.1 Web Link-Up Process

The Merchant creates a Checkout-Order in Zinia and redirects the customer to the URL received in the
response. That URL corresponds to Zinia Link-Up process, where the customer will introduce their date of
birth and validate their phone, so the Checkout-Order can be consolidated into an Order.
Asynchronously, the Merchant will receive a Notification with the final status of the Order. See section
“Order Status Overview” for more information.
This is the most common way to interact with Zinia.

• Related endpoints
• Merchant Login
• Create Checkout Order

2.5.2 Link-Up via API with OTP (Work In Progress)

If the Merchant does not want the customer to go through Zinia Web Link-Up Process, they can retrieve all
the relevant information and create the Order directly in Zinia.

9
In order to do that, the Merchant will have to retrieve the risk data information, Zinia customer legal checks
and payment option quotes (if relevant to the chosen payment option) to be shown in the Checkout
Webpage. When the Customer place the Order, all of this information will be included in the request.
To be able to consolidate the Order, an SMS will be sent to the customer mobile phone with an OTP code.
The customer will have to introduce it in the Merchant Checkout page to be sent across to Zinia for
validation.
No Notifications are needed in this scenario as the response is sent synchronously.

• Related endpoints
• Merchant Login
• Retrieve Risk Data
• Retrieve Customer Legal Checks
• Retrieve Payment Option Quotes
• Submit Order
• Confirm Order

10
2.5.3 Link-Up via API without OTP
If the Merchant does not want the customer to go through Zinia Web Link-Up Process, they can retrieve all
the relevant information and create the Order directly in Zinia.
In order to do that, the Merchant will have to retrieve the risk data information, Zinia customer legal checks
and payment option quotes (if relevant to the chosen payment option) to be shown in the Checkout
Webpage. When the Customer place the Order, all of this information will be included in the request.
This way of integrating is not available by default as it requires a specific approval from Zinia Risk Team
that only will be granted in very specific cases.
No Notifications are needed in this scenario as the response is sent synchronously.

• Related endpoints
• Merchant Login
• Retrieve Risk Data
• Retrieve Customer Legal Checks
• Retrieve Payment Option Quotes
• Create Order

2.6 Order Status Overview

This is an overview of the statuses that an order can have in Zinia:

11
 Status Description

NEW The order was created, but it has not yet been consolidated (still to go
through the Zinia Link-Up and scoring phases).

CHECKOUT_EXPIRED The order has not been consolidated before the "expirationTime". The
customer did not finalise the Zinia Link-Up process within the predefined
time limit.

CHECKOUT_DECLINED The order consolidation process has failed due either to reasons of risk or
fraud or to it being cancelled by the customer prior to its consolidation.

CHECKOUT_COMPLETE The order has been successfully consolidated.

CHECKOUT_FAILED The order consolidation process has failed due to reasons unrelated to risk,
fraud or a customer cancellation.

ORDER_EXPIRED The order has been successfully consolidated, but none of the items has
been shipped within the deadline.

ORDER_CANCELLED All of the order items have been cancelled by the merchant, so nothing will
be shipped to the customer.
If an order is partially cancelled (one or more items of the order have been
cancelled by the merchant, but not all of them) the order will remain in the
“CHECKOUT_COMPLETE” status.

ORDER_SHIPPED All of the order items have been shipped to the customer.
If a partial capture (shipment) of the order is carried out (one or more items
of the order have been shipped to the customer, but not all of them) the
order will remain in the “CHECKOUT_COMPLETE” status.

ORDER_REFUNDED All the order items that were shipped to the customer have been returned,
so the full order will have to be refunded.
If a partial refund of the order is carried out (one or more items of the order
that were shipped to the customer have been returned, but not all of them)
the order will remain in the “ORDER_SHIPPED” status.

This status-flow diagram illustrates the different transitions that could happen within Zinia and how you are
notified of them (synchronous vs. notification process):

12
13
3 Zinia APIs

3.1 Zinia Merchant Security

The API exposes the operations that have to be carried out by you as the merchant due to security
requirements.

3.1.1 Login

This operation carries out the merchant log in based on the credentials provided by the Security Team.
It will give you the “accessToken” to encrypt the “MerchantApiKey” and to obtain the “ApiKey” that will have
to be included in all requests sent to Zinia along with the “accessToken” itself.
The “accessToken” will last for a limited period of time. The expiration information is also contained in the
response of this endpoint in the attribute called "expiresIn".
You can use the same “accessToken” in all API calls while it is valid. When it expires, another one will have
to be requested.
Should you decide to interact with Zinia through a payment gateway, an API Key will be shared with the
gateway that will need to be used in conjunction with your credentials.

3.1.1.1 Parameters
3.1.1.1.1 Body parameters
Name Description

body* {
Required: clientId, clientSecret, grantType

clientId*:
string
Username of the merchant
example: merchant-username-example

clientSecret*:
string
Password of the merchant
example:
a4b8f2170a163d0f64fe7fbe74d0f1976ff90d67196c6620cda21a9c0e4d

grantType*:
string
Indicates the grant type required
Enum: client_credentials
example: client_credentials
}

14
3.1.1.2 Responses
3.1.1.2.1 Status: 200 - OK
Description:
The log-in process has been carried out successfully and the login accessToken can be found in the response.
Schema:
{
accessToken: string Merchant login accessToken
example: EmtSkdWA3Gb37pDiMk1WtWm79eUbiVXsyKDxdoDK6Ic=

expiresIn: integer (int32) Time to session expiration date (in seconds). If conversion fails, it'll
return -1
example: 1199

tokenType: string Token type

example: bearer
}
Example:
{
"accessToken": "xdo65Hr$v2wN$Fldr4HiPq9ZyKFwSh55b3gR2lttFdg=",
"expiresIn": 1199,
"tokenType": "bearer"
}

3.1.1.2.2 Status: 400 – Bad Request

Description:
The server cannot process the request because either some of the mandatory fields are missing or the value
entered in “grantType” is invalid.
Schema:
{
description:
string example: Bad Request, please review it and try again

errorCode: string
example: BAD_REQUEST
}
Example:
{
"description": "Bad Request, please review it and try again",
"errorCode": "BAD_REQUEST"
}

3.1.1.2.3 Status: 500 - Internal server error

Description:
The server encountered an unexpected condition that prevented it from fulfilling the request.
Schema:
{
description: string
example: An error occurred, please try again later
15
 errorCode: string
example: GENERIC_ERROR
}
Example:
{
"description": "An error occurred, please try again later",
"errorCode": "GENERIC_ERROR"
}

3.2 Zinia Checkout API

There are two ways of interacting with Zinia to create an Order:
1. Web Link-Up Process: The Merchant will create a Checkout-Order and redirect the Customer to Zinia
Link-Up process. The Customer will introduce their date of birth and validate their phone, so the
Checkout-Order can be consolidated into an Order.
2. Link-Up via API (with/without OTP): The Merchant will provide all the information regarding the
Customer and also validate the Customer’s phone, so there is no need to go through Zinia Link-Up
process. The Merchant will directly create the Order.
The API exposes the required operations to perform any of the above Order creations:
1. Redirect to Zinia Link-Up Process: This API exposes the endpoint to Create a Checkout Order with
Zinia.
2. Submit Order (Link-Up via API): This API exposes the endpoints to retrieve all the relevant information
regarding the customer: Risk Data, Customer Legal Checks and Payment Option Quotes.

3.2.1 Create Checkout Order

This service creates a checkout order. The response will contain the Link-Up URL where customers have to
be redirected in order to validate their phone number and to complete the purchase. As soon as the
checkout order is consolidated, the order should be processed using the Orders API.

3.2.1.1 Parameters
3.2.1.1.1 Header parameters
Name Description

Authorization* Required

string
Bearer <accessToken>. Where the accessToken has already been obtained in the
response of the “login” endpoint
example: Bearer EmtSkdWA3Gb37pDiMk1WtWm79eUbiVXsyKDxdoDK6Ic=

ApiKey* Required

string

16
 Encrypted ApiKey obtained using the accessToken and the Merchant API Key
provided by Zinia to the merchant and encoded to Base64 format
example: 5810f3dfffd6497db63b8764ba42c4407f6efded

3.2.1.1.2 Body parameters

Name Description

body* {
Required: merchantOrderId, channel, email, customer, addresses,
orderItems, purchaseCountry, purchaseCurrency and orderTotalAmount.

merchantOrderId*: string maxLength:200

Merchant order identifier
example: 900001291100

channel*: string
Channel through which the purchase was carried out:
• ECOMMERCE: The purchase is made through the e-commerce store
and the items are sent to the customer.
• POS: The purchase is made at the physical shop and the customer
leaves with the items.
• POS_HOME_DELIVERY: The purchase is made at the physical store
and the items are sent to the customer.
• CLICKANDCOLLECT: The purchase is made through the e-commerce
store but the items are to be collected by the customer at the physical
store.
• CALL_CENTER: The purchase is made through the Merchant call
centre.
Restrictions:
• When "channel" is informed as "POS":
o BILLING Address is required.
• When "channel" is informed as "ECOMMERCE":
o The same Address has to be sent in both BILLING and
SHIPPING Addresses (both required).
Enum: ECOMMERCE , POS , POS_HOME_DELIVERY , CALL_CENTER
and CLICKANDCOLLECT
example: ECOMMERCE

succesUrl: string maxLength:300

URL to redirect the customer when the order is placed successfully. We
recommend indicating this URL for a good user experience.
example:
https://www.your.shop.tld/callback/success/{transactionId}

pendingUrl: string maxLength:300

URL to redirect the customer when the order is being held. We recommend
indicating this URL for a good user experience.
example:
https://www.your.shop.tld/callback/pending/{transactionId}

17
failureUrl: string maxLength:300
URL to redirect the customer when there was an issue placing the order. We
recommend indicating this URL for a good user experience.
example:
https://www.your.shop.tld/callback/failure/{transactionId}

cancelUrl: string maxLength:300

URL to redirect the customer after clicking the 'Cancel' button in our process.
We recommend indicating this URL for a good user experience.
example:
https://www.your.shop.tld/callback/cancel/{transactionId}

noticeUrl: string maxLength:300

URL where the notification of any change in the order will be sent. You can
find more information about notifications in the Zinia Notification Process
section of this document.
example:
https://www.your.shop.tld/callback/notice/{transactionId}

email*: string maxLength:300

Customer's email address
example: [email protected]

customer*:
Customer's information
{
Required: firstName and lastName

gender: string
Customer's gender
Enum: MALE , FEMALE
example: MALE

firstName*: string
Customer's first name
example: John

lastName*: string
Customer's last name
example: Smith

legalDocuments:
Customer's legal documents (used for identification)
[
Required: docNumber and docType
docNumber*: string
Legal document number
example: 12345678G

docType*: string
Legal document type
Enum: NATIONAL_ID , SSN , FOREIGN_NATIONAL_NUMBER and
PASSPORT

18
 example: NATIONAL_ID
]

title: string
Customer's title
Enum: Mr , Mrs , Miss and Ms
example: Mr

type: string
Customer type
Enum: PERSON
example: PERSON

organizationName: string
Name of the organisation (in the event the customer type is a
company) (Only for B2B customers)
example: IBM

organizationRegistrationId: string
Registration ID of the Organization (in the event that the customer
type is a company) (Only for B2B customers)
example: 123423-CO
}

birthDate: string (date) maxLength:10

Customer’s date of birth. The format is 'yyyy-mm-dd'. ISO 8601 (Date)
example: 1980-11-04

phone: string maxLength:15

Customer's phone number E.164 standard format.
( https://en.wikipedia.org/wiki/E.164)
example: +44123456789

addresses*:
Customer’s addresses:
Restrictions:
• Sending 2 or more addresses with the same value in "addresses.type"
field: SHIPPING / BILLING is not permitted.
• When "channel" is informed as "POS":
o BILLING Address is required.
• When "channel" is informed as "E-COMMERCE":
o The same Address has to be sent in both BILLING and
SHIPPING Addresses (both required).
[ {
Customer’s Address
Required: firstName, lastName, streetName, streetNumber,
postalCode, city, country and type

organizationName: string maxLength:100

Name of the organization (in the event that the customer type is a
company) (Only for B2B customers)
example: IBM

19
title: string
Customer's title
Enum: Mr , Mrs , Miss and Ms
example: Mr

firstName*: string
Customer's first name
example: John

lastName*: string
Customer's last name
example: Smith

streetType: string maxLength:100

Customer's street type
example: Avenue

streetName*: string maxLength:200

Customer's street name
example: Shaftesbury

streetNumber*: string maxLength:5

Customer's street number
example: 113

block: string maxLength:7

Customer's block identifier
example: L

floor: integer (int32)

Customer's floor
example: 1

door: string maxLength:5

Customer's door number
example: B

postalCode*: string maxLength:50

Address postcode
example: W1A 0AX

city*: string maxLength:200

Customer's city
example: Leeds

region: string maxLength:20

Address state/region
example: OH

country*: string maxLength:2

Customer's country, ISO 3166 alpha-2
example: GB

type*: string

20
 Address type
Restrictions:
• When "channel" is informed as "POS":
o BILLING Address is required.
• When "channel" is informed as "ECOMMERCE":
o The same Address has to be sent in both BILLING and
SHIPPING Addresses (both required).
Enum: SHIPPING and BILLING
example: BILLING
} ]

orderItems*:
List of the items in the order
[ {
Item details
Required: name, reference, unitPrice, quantity and totalAmount

name*: string maxLength:100

Item name
example: TV 4k

description: string maxLength:300

Item description
example: AU7000 UHD 4K Smart TV (2021)

brand: string maxLength:100

Item brand
example: Samsung

reference*: string maxLength:200

Item reference
example: 123456

imageUrl: string maxLength:300

Image URL
example: http://.../a.jpeg

unitPrice*: number (double)

Unit price
example: 130

quantity*: integer (int32)

Quantity
example: 1

totalAmount*: number (double)

Total amount = quantity * unitPrice – totalDiscountAmount
example: 130

taxRate: number (double) maximum:100

Tax rate %
example: 10

21
 totalTaxAmount: number (double) maximum:100
Total tax amount based on the tax rate
example: 10

totalDiscountAmount: number (double)

Total discount
example: 10

serialNumber:
Item serial number
[
serialNumber: string
Serial number
example: XRF328871WQ
]
} ]

orderTaxAmount: number (double)

Tax amount
example: 423.9

purchaseCountry*: string maxLength:2

Order country, ISO 3166 alpha-2
example: NL

purchaseCurrency*: string maxLength:3

Purchase currency, ISO 4217
example: EUR

orderDeliveryFee: number (double)

Delivery fee
example: 3.9989

orderTotalAmount*: number (double)

Total Amount. It is calculated as S( orderItems.totalAmount -
orderItems.totalDiscountAmount) + orderDeliveryFee
example: 130

agentOrderId: string maxLength:200

Agent (payment gateway) order identifier
example: HB3434

paymentOptionTypeCode: string maxLength:200

Payment option type code chosen for the order.
If this attribute is not informed, it will take “BNPL” as a default value.
Enum: BNPL, SLICE_IN_3 and INSTALMENTS
example: BNPL

pluginName: string maxLength:100

Name of the e-commerce plugin being used by the merchant
example: Zinia

pluginVersion: string maxLength:100

Version of the e-commerce plugin being used by the merchant
example: 1.7
22
 ecommerceName: string maxLength:100
Name of the e-commerce platform being used by the merchant
example: WooCommerce

ecommerceVersion: string maxLength:200

Version of the e-commerce platform being used by the merchant
example: 6.0.1
}

3.2.1.2 Responses
3.2.1.2.1 Status: 201 – Created
Description:
The checkout order has been created successfully and the Link-Up URL is contained in the response so that
the customer can consolidate the order.
Schema:
{
Required: orderId, status and expirationTime

redirectUrl: string
URL where the customer must be redirected to consolidate the checkout order
example: https://customers.zinia.com/{orderId}

orderId*: string (uuid)

Order identifier
example: 123e4567-e89b-12d3-a456-426614174000

status*: string
Order status. You can find more information about order statuses in the Order Status Overview
section of this document.
Enum: NEW , CHECKOUT_COMPLETE , RISK_FRAUD , FAILED , CANCELLED
example: NEW

expirationTime*: string (date-time)

Date and time when the order status will be set to “EXPIRED” unless it has already been consolidated.
The format is 'YYYY-MM-DDThh:mm[:ss[.nnn]]Z'. ISO 8601 (Datetime) (24-hour format)
example: 2021-02-02T21:46:45.368Z
}
Example:
{
"redirectUrl": "https://Link-Up.stg.cf.zinia.com/8ce93da0-7692-4d0c-9f89-
e756653245f7",
"orderId": "8ce93da0-7692-4d0c-9f89-e756653245f7",
"status": "NEW",
"expirationTime": "2022-10-27T15:50:01.838149906Z"
}

3.2.1.2.2 Status: 400 – Bad Request

Description:

23
The server cannot process the request due to issues regarding the request body, for example:
• The request body is missing.
• Some of the mandatory fields are missing.
• The request body contains data with the wrong format or invalid values or patterns.
• The value entered in “paymentOptionTypeCode” corresponds to a payment option that is not
engaged by the merchant.
Schema:
{
description:
string example: Bad Request, please review it and try again

errorCode: string
example: BAD_REQUEST
}
Examples:
This is the generic bad-request response that may appear:
{
"description": "Bad request, please review it and try again",
"errorCode": "BAD_REQUEST"
}
The description will often contain more details on the fields where the errors have occurred:
• If several fields are incorrect, “BAD_REQUEST” will appear in “errorCode”:
{
"description": "field:[purchaseCurrency], rejected value:[],
field:[purchaseCurrency], rejected value:[], field:[purchaseCurrency], rejected
value:[]",
"errorCode": "BAD_REQUEST"
}
• If there is only one field generating the error, the “errorCode” value will specify it using the format
“fieldName +_MANDATORY”, for example: "STREET_NUMBER_MANDATORY",
"TOTAL_AMOUNT_MANDATORY", "STREET_NAME_MANDATORY", "QUANTITY_MANDATORY",
"FIRST_NAME_MANDATOR", etc.
{
"description": "field:[orderItems[0].totalAmount], rejected value:[null]",
"errorCode": " TOTAL_AMOUNT_MANDATORY"
}

3.2.1.2.3 Status: 401 – Unauthorized

Description:
Either the access token in the “Authorization” header or the API Key in the “ApiKey” header is missing or
invalid.
Schema:
{
description:
string example: The request lacks valid authentication credentials for the
target resource

errorCode: string
example: UNAUTHORIZED
}

24
Example:
This is the generic unauthorized response:
{
"description": " Unauthorized!",
"errorCode": "UNAUTHORIZED"
}
However, a HTML response may also appear:
<head><title>401 Authorization Required</title></head>
<body>
<center><h1>401 Authorization Required</h1></center>
<hr><center>openresty/1.21.4.1</center>
</body>
</html>

3.2.1.2.4 Status: 403 – Forbidden

Description:
This would happen if your token did not have the rights required to create a checkout.
Schema:
{
description: string
example: The request has not been authorized

errorCode: string
example: FORBIDDEN
}
Example:
{
"description": " Operation cannot be executed",
"errorCode": " FORBIDDEN"
}

3.2.1.2.5 Status: 500 - Internal server error

Description:
Something went wrong regarding either Zinia or one of its partners. As such, the checkout order could not
be created.
Schema:
{
description: string
example: The request was not fulfilled due to an unexpected condition

errorCode: string
example: GENERIC_ERROR
}
Example:
{
"description": "An error occurred, please try again later",
"errorCode": "GENERIC_ERROR"
}

25
3.2.2 Retrieve Risk Data

This service retrieves the risk data information needed to Create an Order without going through the Zinia
Link-Up process (Create Order / Submit Order / Link-Up via API).

3.2.2.1 Parameters
3.2.2.1.1 Header parameters
Name Description

Authorization* Required

string
Bearer <accessToken>. Where the accessToken has already been obtained in the
response of the “login” endpoint
example: Bearer EmtSkdWA3Gb37pDiMk1WtWm79eUbiVXsyKDxdoDK6Ic=

ApiKey* Required

string
Encrypted ApiKey obtained using the accessToken and the Merchant API Key
provided by Zinia to the merchant and encoded to Base64 format
example: 5810f3dfffd6497db63b8764ba42c4407f6efded

3.2.2.1.2 Query String parameters

Name Description

country* Required

string
Country where the Order is going to be Purchased, ISO 3166 alpha-2
example: DE

3.2.2.2 Responses
3.2.2.2.1 Status: 200 – OK
Description:
The risk data has been retrieved successfully and it is contained in the Payload of the response.
Schema:
{
Required: tmxId and orgId

tmxId*: string (uuid)

ThreatMetrix identifier to inform about the Customer browser data
example: 2006cb55595d9fbf7a142e90f97cccc7

26
 orgId*: string
Organization Identifier for the logged merchant
example: bstxgewe
}
Example:
{
"tmxId":"2006cb55595d9fbf7a142e90f97cccc7",
"orgId": "bstxgewe"
}

3.2.2.2.2 Status: 204 – No Content

Description:
The server has successfully fulfilled the request but there is no risk data to show for the requested search
criteria.
Schema:
N/A
Example:
N/A

3.2.2.2.3 Status: 400 – Bad Request

Description:
The server cannot process the request due to issues regarding the request, for example:
• The mandatory query string parameter is missing.
• The query string parameter contains data with the wrong format or invalid values or patterns.
Schema:
{
description:
string example: Bad Request, please review it and try again

errorCode: string
example: BAD_REQUEST
}
Examples:
This is the generic bad-request response that may appear:
{
"description": "Bad request, please review it and try again",
"errorCode": "BAD_REQUEST"
}

3.2.2.2.4 Status: 401 – Unauthorized

Description:
Either the access token in the “Authorization” header or the API Key in the “ApiKey” header is missing or
invalid.
Schema:
{
description:
string example: The request lacks valid authentication credentials for the
target resource
27
 errorCode: string
example: UNAUTHORIZED
}
Example:
This is the generic unauthorized response:
{
"description": " Unauthorized!",
"errorCode": "UNAUTHORIZED"
}
However, a HTML response may also appear:
<head><title>401 Authorization Required</title></head>
<body>
<center><h1>401 Authorization Required</h1></center>
<hr><center>openresty/1.21.4.1</center>
</body>
</html>

3.2.2.2.5 Status: 403 – Forbidden

Description:
This would happen if your token did not have the rights required to retrieve the risk data.
Schema:
{
description: string
example: The request has not been authorized

errorCode: string
example: FORBIDDEN
}
Example:
{
"description": " Operation cannot be executed",
"errorCode": " FORBIDDEN"
}

3.2.2.2.6 Status: 500 - Internal server error

Description:
Something went wrong regarding either Zinia or one of its partners. As such, the risk data could not be
retrieved.
Schema:
{
description: string
example: The request was not fulfilled due to an unexpected condition

errorCode: string
example: GENERIC_ERROR
}
Example:
{
"description": "An error occurred, please try again later",
"errorCode": "GENERIC_ERROR"
28
}

3.2.3 Retrieve Customer Legal Checks

This service retrieves the Customer legal information that needs to be checked by the Customer to be able
to Create an Order without going through the Zinia Link-Up process (Create Order / Submit Order / Link-Up
via API).

3.2.3.1 Parameters
3.2.3.1.1 Header parameters
Name Description

Authorization* Required

string
Bearer <accessToken>. Where the accessToken has already been obtained in the
response of the “login” endpoint
example: Bearer EmtSkdWA3Gb37pDiMk1WtWm79eUbiVXsyKDxdoDK6Ic=

ApiKey* Required

string
Encrypted ApiKey obtained using the accessToken and the Merchant API Key
provided by Zinia to the merchant and encoded to Base64 format
example: 5810f3dfffd6497db63b8764ba42c4407f6efded

applicationLocale* Required

string
Language in which the Consumer wants to retrieve the information.
Format: Language Code (Two lowercase alphanumeric positions as per ISO 639-
1) - Country Code (Two uppercase alphanumeric positions as per ISO 3166-1).
example: en-EN

3.2.3.1.2 Query String parameters

Name Description

country string
Country where the Order is going to be Purchased, ISO 3166 alpha-2
example: DE

3.2.3.2 Responses
3.2.3.2.1 Status: 200 – OK
Description:
The Customer legal checks have been retrieved successfully and they are contained in the Payload of the
response.
29
Schema:
{
consents:
List of consents to be shown to the Customer in the Checkout webpage
[ {
Required: documentId, title, text, metadata, sortOrder and required.

documentId*: string
Consent identifier
example: product_offerings

title*: string
Tittle of the consent to be shown in the Checkout webpage
example: Our products and services

text*: string
Text of the consent to be shown in the Checkout webpage.
This text can contain links to URLs and they will be informed with the tag “<urlName>”, for
example, “<urlPrivacy>”. Those URLs will be informed in the fields
“consents.metadata.assetsLinks.url_name”, for example,
“consents.metadata.assetsLinks.url_privacy”.
example: By ticking this box, […]

metadata*:
Metadata information regarding the consent: Internal data and Link URLs to be embedded in
the Text of the Consent.
{
Required: poEditorKey.

poEditorKey*: string
Key of the consent within Zinia Document Management System.
example: productOfferingsCategoryNameDescription.countryDE

poEditorText: string
Text of the consent within Zinia Document Management System.
example: By ticking this box, […]

assetsLinks:
URLs to be embedded in the links included in the Consent Text (field “consents.text”).
The consent text can contain links to URLs and they will be informed with the tag
“<urlName>”, for example, “<urlPrivacy>”. Those URLs will be informed in this fields.
{
< * >: string
The name of the attribute will be the name of the link within the consent text in
snake_case. If the tag in the consent text is “emailPrivacy”, the name of this
attribute will be “email_privacy”.
The value of the attribute will be the URL to be embedded on the link.
example: "email_privacy": "[email protected]"
}
}

sortOrder*: integer (int32)

Place (order) of the consent within the list

30
 example: 1

required*: boolean
Whether it is required or not to inform about this Consent in the Creation of the Order (Submit)
example: true
} ]

terms:
List of terms and conditions to be shown to the Customer in the Checkout webpage
[ {
Required: documentId, title, text, metadata, sortOrder and required.

documentId*: string
Term and condition identifier
example: terms_Link-Up_general

title*: string
Tittle of the term and condition to be shown in the Checkout webpage
example: Terms and Conditions

text*: string
Text of the term and condition to be shown in the Checkout webpage.
This text can contain links to URLs and they will be informed with the tag “<urlName>”, for
example, “<pdfTerms>”. Those URLs will be informed in the fields
“terms.metadata.assetsLinks.url_name”, for example,
“terms.metadata.assetsLinks.pdf_terms”.
example: I accept Zinia's […]

metadata*:
Metadata information regarding the term and condition: Internal data and Link URLs to be
embedded in the Text of the term and condition.
{
Required: poEditorKey.

poEditorKey*: string
Key of the term and condition within Zinia Document Management System.
example: termsLink-UpGeneralCategoryNameDescription.countryDE

poEditorText: string
Text of the term and condition within Zinia Document Management System.
example: I accept Zinia's […]

assetsLinks:
URLs to be embedded in the links included in the term and condition text (field
“terms.text”).
The term and condition text can contain links to URLs and they will be informed with
the tag “<urlName>”, for example, “<pdfTerms >”. Those URLs will be informed in this
fields.
{
< * >: string
The name of the attribute will be the name of the link within the term and
condition text in snake_case. If the tag in the term and condition text is
“pdfTerms”, the name of this attribute will be “pdf_terms”.

31
 The value of the attribute will be the URL to be embedded on the link.
example: "pdf_terms": "
https://www.zinia.com/assets/TERMS.pdf"
}
}

sortOrder*: integer (int32)

Place (order) of the term and condition within the list
example: 1

required*: boolean
Whether it is required or not to inform about this term and condition in the Creation of the
Order (Submit)
example: true
} ]

policies:
List of policies to be shown to the Customer in the Checkout webpage
[ {
Required: documentId, title, text, metadata, sortOrder and required.

documentId*: string
Policy identifier
example: privacy_Link-Up

title*: string
Tittle of the policy to be shown in the Checkout webpage
example: Privacy Policy

text*: string
Text of the policy to be shown in the Checkout webpage.
This text can contain links to URLs and they will be informed with the tag “<urlName>”, for
example, “<pdfPrivacy>”. Those URLs will be informed in the fields
“policies.metadata.assetsLinks.url_name”, for example,
“policies.metadata.assetsLinks.pdf_privacy”.
example: I have read and accept […]

metadata*:
Metadata information regarding the policy: Internal data and Link URLs to be embedded in
the Text of the policy.
{
Required: poEditorKey.

poEditorKey*: string
Key of the policy within Zinia Document Management System.
example: privacyLink-UpAPICategoryNameDescription.countryDE

poEditorText: string
Text of the policy within Zinia Document Management System.
example: I have read and accept […]

assetsLinks:
URLs to be embedded in the links included in the policy text (field “policies.text”).

32
 The policy text can contain links to URLs and they will be informed with the tag
“<urlName>”, for example, “<pdfPrivacy>”. Those URLs will be informed in this fields.
{
< * >: string
The name of the attribute will be the name of the link within the policy text in
snake_case. If the tag in the consent text is “pdfPrivacy”, the name of this
attribute will be “pdf_privacy”.
The value of the attribute will be the URL to be embedded on the link.
example: "pdf_privacy": "
https://www.zinia.com/assets/PRIVACY_POLICY.pdf"
}
}

sortOrder*: integer (int32)

Place (order) of the policy within the list
example: 1

required*: boolean
Whether it is required or not to inform about this policy in the Creation of the Order (Submit)
example: true
} ]
}
Example:
{
"consents": [
{
"documentId": "product_offerings",
"title": "Our products and services",
"text": "By ticking this box, you consent to Zinia (Open Bank S.A.), as data
controller, sending you customised marketing (by SMS, instant messaging applications,
email, push notifications, pop-ups or any other electronic or telematic means)
relating to its products and services that may interest you and based on your customer
profile, which has been created in accordance with Zinia's internal risk criteria
and <urlPrivacy>external source</urlPrivacy> consultations. You can exercise your
personal data rights, including withdrawal of your consent, by sending an email to
<emailPrivacy>[email protected]</emailPrivacy>. For further information, see
Zinia's <urlPrivacy>Privacy Policy</urlPrivacy>.\n",
"metadata": {
"poEditorKey":
"clLowlands.services.personalData.userInformation.marketingConsents.clMarketingCons
ents.productOfferingsCategoryNameDescription.countryDE",
"poEditorText": "By ticking this box, you consent to Zinia (Open Bank S.A.),
as data controller, sending you customised marketing (by SMS, instant messaging
applications, email, push notifications, pop-ups or any other electronic or telematic
means) relating to its products and services that may interest you and based on your
customer profile, which has been created in accordance with Zinia's internal risk
criteria and <urlPrivacy>external source</urlPrivacy> consultations. You can
exercise your personal data rights, including withdrawal of your consent, by sending
an email to <emailPrivacy>[email protected]</emailPrivacy>. For further
information, see Zinia's <urlPrivacy>Privacy Policy</urlPrivacy>.\n",
"assetsLinks": {
"url_privacy": "https://www.zinia.com/assets/CF_DE/de-
DE/documents/v1/DE.ZINIA.LINK-UP.PRIVACY_POLICY.pdf",
"url_santander": "https://www.zinia.com/assets/CF_DE/de-
DE/documents/v1/DE.ZINIA.LINK-UP.PRIVACY_POLICY.DOCUMENT.ENTITIES.pdf",
"pdf_privacy": "https://www.zinia.com/assets/CF_DE/de-
DE/documents/v1/DE.ZINIA.LINK-UP.PRIVACY_POLICY.pdf",
"pdf_terms": "https://www.zinia.com/assets/CF_DE/de-
DE/documents/v1/DE.ZINIA.LINK-UP.TERMS_AND_CONDITIONS_CUSTOMERS.pdf",

33
 "email_privacy": "[email protected]"
}
},
"sortOrder": 2,
"required": false
}
],
"terms": [
{
"documentId": "terms_Link-Up_general",
"title": "Terms and Conditions",
"text": "I accept Zinia's <pdfTerms>Terms and Conditions</pdfTerms> (including
applicable collection costs for late payment) and its <pdfPrivacy>Privacy
Policy</pdfPrivacy>.",
"metadata": {
"poEditorKey":
"clLowlands.services.personalData.userInformation.termsAndConditions.clTermsAndCond
itions.termsLink-UpGeneralCategoryNameDescription.countryDE",
"poEditorText": "I accept Zinia's <pdfTerms>Terms and Conditions</pdfTerms>
(including applicable collection costs for late payment) and its <pdfPrivacy>Privacy
Policy</pdfPrivacy>.",
"assetsLinks": {
"url_privacy": "https://www.zinia.com/assets/CF_DE/de-
DE/documents/v1/DE.ZINIA.LINK-UP.PRIVACY_POLICY.pdf",
"url_santander": "https://www.zinia.com/assets/CF_DE/de-
DE/documents/v1/DE.ZINIA.LINK-UP.PRIVACY_POLICY.DOCUMENT.ENTITIES.pdf",
"pdf_privacy": "https://www.zinia.com/assets/CF_DE/de-
DE/documents/v1/DE.ZINIA.LINK-UP.PRIVACY_POLICY.pdf",
"pdf_terms": "https://www.zinia.com/assets/CF_DE/de-
DE/documents/v1/DE.ZINIA.LINK-UP.TERMS_AND_CONDITIONS_CUSTOMERS.pdf",
"email_privacy": "[email protected]"
}
},
"sortOrder": 1,
"required": false
}
],
"policies": [
{
"documentId": "privacy_Link-Up",
"title": "Privacy Policy",
"text": "I have read and accept the <pdfPrivacy>Privacy Policy</pdfPrivacy>",
"metadata": {
"poEditorKey":
"clLowlands.services.personalData.userInformation.PrivacyPolicy.clPrivacyPolicy.pri
vacyLink-UpAPICategoryNameDescription.countryDE",
"poEditorText": "I have read and accept the <pdfPrivacy>Privacy
Policy</pdfPrivacy>",
"assetsLinks": {
"url_privacy": "https://www.zinia.com/assets/CF_DE/de-
DE/documents/v1/DE.ZINIA.LINK-UP.PRIVACY_POLICY.pdf",
"url_santander": "https://www.zinia.com/assets/CF_DE/de-
DE/documents/v1/DE.ZINIA.LINK-UP.PRIVACY_POLICY.DOCUMENT.ENTITIES.pdf",
"pdf_privacy": "https://www.zinia.com/assets/CF_DE/de-
DE/documents/v1/DE.ZINIA.LINK-UP.PRIVACY_POLICY.pdf",
"pdf_terms": "https://www.zinia.com/assets/CF_DE/de-
DE/documents/v1/DE.ZINIA.LINK-UP.TERMS_AND_CONDITIONS_CUSTOMERS.pdf",
"email_privacy": "[email protected]"
}
},
"sortOrder": 1,
"required": false
}
]

34
}

3.2.3.2.2 Status: 204 – No Content

Description:
The server has successfully fulfilled the request but there are no Customer legal Checks to show for the
requested search criteria.
Schema:
N/A
Example:
N/A

3.2.3.2.3 Status: 400 – Bad Request

Description:
The server cannot process the request due to issues regarding the request, for example:
• The mandatory header “applicationLocale” is missing.
• The query string parameter or header “applicationLocale” contains data with the wrong format or
invalid values or patterns.
Schema:
{
description:
string example: Bad Request, please review it and try again

errorCode: string
example: BAD_REQUEST
}
Examples:
This is the generic bad-request response that may appear:
{
"description": "Bad request, please review it and try again",
"errorCode": "BAD_REQUEST"
}

3.2.3.2.4 Status: 401 – Unauthorized

Description:
Either the access token in the “Authorization” header or the API Key in the “ApiKey” header is missing or
invalid.
Schema:
{
description:
string example: The request lacks valid authentication credentials for the
target resource

errorCode: string
example: UNAUTHORIZED
}
Example:
This is the generic unauthorized response:

35
{
"description": " Unauthorized!",
"errorCode": "UNAUTHORIZED"
}
However, a HTML response may also appear:
<head><title>401 Authorization Required</title></head>
<body>
<center><h1>401 Authorization Required</h1></center>
<hr><center>openresty/1.21.4.1</center>
</body>
</html>

3.2.3.2.5 Status: 403 – Forbidden

Description:
This would happen if your token did not have the rights required to retrieve the Customer legal checks.
Schema:
{
description: string
example: The request has not been authorized

errorCode: string
example: FORBIDDEN
}
Example:
{
"description": " Operation cannot be executed",
"errorCode": " FORBIDDEN"
}

3.2.3.2.6 Status: 500 - Internal server error

Description:
Something went wrong regarding either Zinia or one of its partners. As such, the Customer legal checks could
not be retrieved.
Schema:
{
description: string
example: The request was not fulfilled due to an unexpected condition

errorCode: string
example: GENERIC_ERROR
}
Example:
{
"description": "An error occurred, please try again later",
"errorCode": "GENERIC_ERROR"
}

3.2.4 Retrieve Payment Option Quotes

36
In case the Customer wants to select the INSTALLMENTS Payment Option in Zinia, this endpoint will retrieve
the simulation of the quotes based on the available Payment Options of the Merchant.

3.2.4.1 Parameters
3.2.4.1.1 Header parameters
Name Description

Authorization* Required

string
Bearer <accessToken>. Where the accessToken has already been obtained in the
response of the “login” endpoint
example: Bearer EmtSkdWA3Gb37pDiMk1WtWm79eUbiVXsyKDxdoDK6Ic=

ApiKey* Required

string
Encrypted ApiKey obtained using the accessToken and the Merchant API Key
provided by Zinia to the merchant and encoded to Base64 format
example: 5810f3dfffd6497db63b8764ba42c4407f6efded

3.2.4.1.2 Query String parameters

Name Description

channel* Required

string
Channel through which the purchase was carried out:
• ECOMMERCE: The purchase is made through the e-commerce store and the
items are sent to the customer.
• POS: The purchase is made at the physical shop and the customer leaves with
the items.
• POS_HOME_DELIVERY: The purchase is made at the physical store and the
items are sent to the customer.
• CLICKANDCOLLECT: The purchase is made through the e-commerce store but
the items are to be collected by the customer at the physical store.
• CALL_CENTER: The purchase is made through the Merchant call centre.
Enum: ECOMMERCE , POS , POS_HOME_DELIVERY , CALL_CENTER and CLICKANDCOLLECT
example: ECOMMERCE
amount* Required

number (double)
Total Amount of the Order.
example: 736

3.2.4.2 Responses
3.2.4.2.1 Status: 200 – OK
Description:
37
The payment option quotes have been retrieved successfully and they are contained in the Payload of the
response.
Schema:
{
paymentOptions:
List of available Payment Options for the Merchant.
[ {
Required: paymentOptionId, paymentOptionCode, paymentOptionTypeCode, and data.

paymentOptionId*: string
Payment Option internal identifier
Enum: PAY_IN_14 , PAY_IN_30 , SLICE_IN_3 , PAY_IN_3M , PAY_IN_6M , PAY_IN_12M ,
PAY_IN_18M , PAY_IN_24M and PAY_IN_36M
example: PAY_IN_30

paymentOptionCode*: string
Payment Option internal code
Enum: PAY_IN_14 , PAY_IN_30 , SLICE_IN_3 , PAY_IN_3M , PAY_IN_6M , PAY_IN_12M ,
PAY_IN_18M , PAY_IN_24M and PAY_IN_36M
example: PAY_IN_30

paymentOptionTypeCode*: string
Payment Option Type internal code
Enum: BNPL , SLICE_IN_3 and INSTALLMENTS
example: BNPL

data*:
Payment information for this Payment Option.
{
Required: numberOfInstallments, purchaseCurrency, totalAmount and
installments.

numberOfInstallments*: integer (int32)

Number of scheduled payments to be collected by Zinia
example: 3

purchaseCurrency*: string
Currency of the purchase, ISO 4217
example: EUR

totalAmount*: number (double)

Total amount of the purchase
example: 150

installments*:
List of the scheduled payments to be collected by Zinia. The number of elements in this
list will be the same as the value of the attribute
“paymentOptions.data.numberOfInstallments”.
[ {
Required: sequenceNumber and amount.

38
 sequenceNumber*: integer (int32)
Sequence number of this instalment
example: 1

amount*: number (double)

Amount of this instalment
example: 50
} ]
}
} ]
}
Example:
{
"paymentOptions": [
{
"paymentOptionId": "PAY_IN_30",
"paymentOptionCode": "PAY_IN_30",
"paymentOptionTypeCode": "BNPL",
"data": {
"numberOfInstallments": 1,
"purchaseCurrency": "EUR",
"totalAmount": 100,
"installments": [
{
"sequenceNumber": 1,
"amount": 100.00
}
]
}
},
{
"paymentOptionId": "SLICE_IN_3",
"paymentOptionCode": "SLICE_IN_3",
"paymentOptionTypeCode": "SLICE_IN_3",
"data": {
"numberOfInstallments": 3,
"purchaseCurrency": "EUR",
"totalAmount": 100,
"installments": [
{
"sequenceNumber": 1,
"amount": 33.34
},
{
"sequenceNumber": 2,
"amount": 33.33
},
{
"sequenceNumber": 3,
"amount": 33.33
}
]
}
}
]
}

3.2.4.2.2 Status: 204 – No Content

Description:

39
The server has successfully fulfilled the request but there are no payment option quotes to show for the
requested search criteria.
Schema:
N/A
Example:
N/A

3.2.4.2.3 Status: 400 – Bad Request

Description:
The server cannot process the request due to issues regarding the request, for example:
• The mandatory quey string parameter is missing.
• The query string parameters contains data with the wrong format or invalid values or patterns.
Schema:
{
description:
string example: Bad Request, please review it and try again

errorCode: string
example: BAD_REQUEST
}
Examples:
This is the generic bad-request response that may appear:
{
"description": "Bad request, please review it and try again",
"errorCode": "BAD_REQUEST"
}

3.2.4.2.4 Status: 401 – Unauthorized

Description:
Either the access token in the “Authorization” header or the API Key in the “ApiKey” header is missing or
invalid.
Schema:
{
description:
string example: The request lacks valid authentication credentials for the
target resource

errorCode: string
example: UNAUTHORIZED
}
Example:
This is the generic unauthorized response:
{
"description": " Unauthorized!",
"errorCode": "UNAUTHORIZED"
}
However, a HTML response may also appear:

40
<head><title>401 Authorization Required</title></head>
<body>
<center><h1>401 Authorization Required</h1></center>
<hr><center>openresty/1.21.4.1</center>
</body>
</html>

3.2.4.2.5 Status: 403 – Forbidden

Description:
This would happen if your token did not have the rights required to retrieve the payment option quotes.
Schema:
{
description: string
example: The request has not been authorized

errorCode: string
example: FORBIDDEN
}
Example:
{
"description": " Operation cannot be executed",
"errorCode": " FORBIDDEN"
}

3.2.4.2.6 Status: 500 - Internal server error

Description:
Something went wrong regarding either Zinia or one of its partners. As such, the payment option quotes
could not be retrieved.
Schema:
{
description: string
example: The request was not fulfilled due to an unexpected condition

errorCode: string
example: GENERIC_ERROR
}
Example:
{
"description": "An error occurred, please try again later",
"errorCode": "GENERIC_ERROR"
}

3.3 Zinia Link-Up API (Work In Progress)

If the Merchant does not want the customer to go through Zinia Web Link-Up Process, they can retrieve all
the relevant information and create the Order directly in Zinia.
This API will provide the required endpoints to complete the two-step process:
1. Submit the order to Zinia.
2. Confirm the order by informing the OTP code sent to the customer by SMS to the phone informed in
the first step. The order will be consolidated as soon as the OTP code is validated.
41
3.3.1 Submit Order

This service submits an Order to Zinia. This operation will have to include the risk data information, Zinia
customer legal checks and payment option quotes (if relevant to the chosen payment option) as part of the
request:
• Retrieve Risk Data
• Retrieve Customer Legal Checks
• Retrieve Payment Option Quotes
All the details regarding this endpoint (Parameters & Responses) are still being developed. This section will
be completed as soon as the service is available for consumption.

3.3.2 Confirm Order

To be able to consolidate the Order submitted in the previous step, an OTP code will be sent by SMS to the
customer mobile phone. This endpoint will be the one responsible of the validation of that code and
consolidation of the Order.
All the details regarding this endpoint (Parameters & Responses) are still being developed. This section will
be completed as soon as the service is available for consumption.

3.4 Zinia Orders API

This API exposes the operations required to manage an order generated in Zinia using the Checkout API (the
customer has to go through the Link-Up process) or the direct order-creation endpoint (the Link-Up via API
process):
• Capture fully/partially an order.
• Cancel fully/partially an order.
• Refund fully/partially an order.
It also exposes the endpoint to directly create an order in Zinia, without the customer having to go through
the website Link-Up process (this is known as Link-Up-via API process).

3.4.1 Create Order

This service creates an order in Zinia. This endpoint and that in the Checkout API should not be mixed up:
• This endpoint directly creates an order in Zinia.
• The endpoint in the Checkout API creates a checkout order in Zinia. The Customer has to complete
the web Link-Up process to consolidate the checkout order and convert it into an order.
The response body will contain the order identifier and its status.

42
3.4.1.1 Parameters
3.4.1.1.1 Header parameters
Name Description

Authorization* Required

string
Bearer <accessToken>. Where the accessToken has already been obtained in the
response of the “login” endpoint
example: Bearer EmtSkdWA3Gb37pDiMk1WtWm79eUbiVXsyKDxdoDK6Ic=

ApiKey* Required

string
Encrypted ApiKey obtained using the accessToken and the merchant API Key
provided by Zinia to the merchant and encoded to Base64 format
example: 5810f3dfffd6497db63b8764ba42c4407f6efded

3.4.1.1.2 Body parameters

Name Description

body* {
Required: channel, birthdate, merchantOrderId, unverifiedCustomer,
userIpAddress, addresses, orderItems, purchaseCountry,
purchaseCurrency, orderTotalAmount and purchaseDate.

channel*: string
Channel through which the purchase was carried out:
• ECOMMERCE: The purchase is made through the e-commerce store
and the items are sent to the customer.
• POS: The purchase is made at the physical store and the customer
leaves with the items.
• POS_HOME_DELIVERY: The purchase is made at the physical store
and the items are sent to the customer.
• CALL_CENTER: The purchase is made through a telephone call.
• CLICKANDCOLLECT: The purchase is made through the e-commerce
store and the items are to be collected by the customer at the physical
store.
Restrictions:
• When "channel" is informed as "POS":
o BILLING Address is required.
• When "channel" is informed as "ECOMMERCE":
o The same Address has to be sent in both BILLING and
SHIPPING Addresses (both required).
Enum: ECOMMERCE , CLICKANDCOLLECT , POS_HOME_DELIVERY , CALL_CENTER
and POS
example: E-COMMERCE

birthDate*: string (date) maxLength:10

43
Customer’s date of birth. The format is 'yyyy-mm-dd'. ISO 8601 (Date)
example: 1980-11-04

phone: string maxLength:15

Customer's phone number E.164 standard format.
( https://en.wikipedia.org/wiki/E.164)
example: +44123456789

merchantOrderId*: string maxLength:200

Merchant order identifier
example: 900001291100

succesUrl: string maxLength:300

URL to redirect the customer when the order is placed successfully. We
recommend indicating this URL for a good user experience.
example:
https://www.your.shop.tld/callback/success/{transactionId}

pendingUrl: string maxLength:300

URL to redirect the customer when the order is being held. We recommend
indicating this URL for a good user experience.
example:
https://www.your.shop.tld/callback/pending/{transactionId}

failureUrl: string maxLength:300

URL to redirect the customer when there was an issue placing the order. We
recommend indicating this URL for a good user experience.
example:
https://www.your.shop.tld/callback/failure/{transactionId}

cancelUrl: string maxLength:300

URL to redirect customer after clicking the 'Cancel' button in our process. We
recommend indicating this URL for a good user experience.
example:
https://www.your.shop.tld/callback/cancel/{transactionId}

noticeUrl: string maxLength:300

URL where the notification of any change in the order will be sent. You can
see more information about notifications in the Zinia Notification Process
section of this document.
example:
https://www.your.shop.tld/callback/notice/{transactionId}

email*: string maxLength:300

Customer's email address
example: [email protected]

unverifiedCustomer*:
Unverified customer information
{
Required: firstName and lastName

gender: string
Customer's gender

44
Enum: MALE , FEMALE
example: MALE

firstName*: string
Customer's first name
example: John

lastName*: string
Customer's last name
example: Smith

legalDocuments:
Customer's legal documents
[
docNumber: string
Legal document number
example: 12345678G

docType: string
Legal document type
Enum: NATIONAL_ID , SSN , FOREIGN_NATIONAL_NUMBER and
PASSPORT
example: NATIONAL_ID
]

title: string
Customer's title
Enum: Mr , Mrs , Miss and Ms
example: Mr

type: string
Customer type
Enum: PERSON
example: PERSON

organizationName: string
Name of the organization (in the event that the Customer type is a
company) (Only for B2B customers)
example: IBM

organizationRegistrationId: string
Registration ID of the organization (in the event that the customer
type is a company) (Only for B2B customers)
example: 123423-CO

language: string
Language of the unverified customer in format “ll-LL”, where:
• ll: Language Code: Two lowercase alphanumeric positions as
per ISO 639-1.
• LL: Country Code: Two uppercase alphanumeric positions as
per ISO 3166-1 Alpha-2.
example: en-GB

45
 consents:
Consents to be created along with the unverified customer.
[ {
Required: documentId

documentId*: string
Consent Identifier
example: external_resources

value: boolean
Accepted/Rejected value for the current consent
example: true
} ]

terms:
Terms to be created along with the unverified customer.
[ {
Required: documentId

documentId*: string
Term Identifier
example: external_resources

value: boolean
Accepted/Rejected value for the current term
example: true
} ]

policies:
Policies to be created along with the unverified customer.
[ {
Required: documentId

documentId*: string
Policy identifier
example: external_resources

value: boolean
Accepted/Rejected value for the current policy
example: false
} ]
}

userIpAddress*: string
Unverified customer's IP Address
example: 124.0.0.1

addresses*:
Customer’s addresses:
Restrictions:
• Sending 2 or more addresses with the same value in "addresses.type"
field: SHIPPING / BILLING is not permitted.
• When "channel" is informed as "POS":
o BILLING Address is required.
46
 • When "channel" is informed as "ECOMMERCE":
o The same Address has to be sent in both BILLING and
SHIPPING Addresses (both required).
[ {
Customer’s Address
Required: firstName, lastName, streetName, streetNumber,
postalCode, city, country and type

organizationName: string maxLength:100

Name of the organization (in the event that the customer type is a
company) (Only for B2B customers)
example: IBM

title: string
Customer's title
Enum: Mr , Mrs , Miss and Ms
example: Mr

firstName*: string
Customer's first name
example: John

lastName*: string
Customer's last name
example: Smith

streetType: string maxLength:100

Customer's street type
example: Avenue

streetName*: string maxLength:200

Customer's street name
example: Shaftesbury

streetNumber*: string maxLength:5

Customer's street number
example: 113

block: string maxLength:7

Customer's block identifier
example: L

floor: integer (int32)

Customer's floor
example: 1

door: string maxLength:5

Customer's door number
example: B

postalCode*: string maxLength:50

Address postcode
example: W1A 0AX

47
 city*: string maxLength:200
Customer's city
example: Leeds

region: string maxLength:20

Address state/region
example: OH

country*: string maxLength:2

Customer's country, ISO 3166 alpha-2
example: GB

type*: string
Address type
Restrictions:
• When "channel" is informed as "POS":
o BILLING Address is required.
• When "channel" is informed as "ECOMMERCE":
o The same Address has to be sent in both BILLING and
SHIPPING Addresses (both required).
Enum: SHIPPING and BILLING
example: BILLING
} ]

orderItems*:
List of the items in the order
[ {
Item details
Required: name, reference, unitPrice, quantity and totalAmount

name*: string maxLength:100

Item name
example: TV 4k

description: string maxLength:300

Item's description
example: AU7000 UHD 4K Smart TV (2021)

brand: string maxLength:100

Item brand
example: Samsung

reference*: string maxLength:200

Item reference
example: 123456

imageUrl: string maxLength:300

Image URL
example: http://.../a.jpeg

unitPrice*: number (double)

Unit price
example: 130

48
 quantity*: integer (int32)
Quantity
example: 1

totalAmount*: number (double)

Total Amount = quantity * unitPrice – totalDiscountAmount
example: 130

taxRate: number (double) maximum:100

Tax rate %
example: 10

totalTaxAmount: number (double) maximum:100

Total tax amount based on the tax rate
example: 10

totalDiscountAmount: number (double)

Total discount
example: 10

serialNumber:
Items’ serial numbers
[
serialNumber: string
Serial number
example: XRF328871WQ
]
} ]

orderTaxAmount: number (double)

Tax amount
example: 423.9

paymentOptionId: string
Payment option internal identifier chosen for the order
Enum: PAY_IN_14 , PAY_IN_30 , SLICE_IN_3 , PAY_IN_3M , PAY_IN_6M ,
PAY_IN_12M , PAY_IN_18M , PAY_IN_24M and PAY_IN_36M .
example: PAY_IN_30

purchaseCountry*: string maxLength:2

Order country, ISO 3166 alpha-2
example: NL

purchaseCurrency*: string maxLength:3

Purchase currency, ISO 4217
example: EUR

orderDeliveryFee: number (double)

Delivery fee
example: 3.9989

orderTotalAmount*: number (double)

49
Total amount. It is calculated as S( orderItems.totalAmount -
orderItems.totalDiscountAmount) + orderDeliveryFee
example: 130

browserInfo:
Unverified customer’s browser information
{
Required: javaEnabled, javascriptEnabled, cookiesEnabled,
language, platform, screenColorDepth, screenHeight, screenWidth,
timeZone, userAgent and acceptHeader.

javaEnabled*: boolean
Flag to indicate whether Java is enabled in the browser
example: true

javascriptEnabled*: boolean
Flag to indicate whether JavaScript is enabled in the browser
example: true

cookiesEnabled*: boolean
Flag to indicate whether the cookies are enabled in the browser
example: true

language*: string
Language of the browser in format “ll-LL”, where:
• ll: Language Code: Two lowercase alphanumeric positions as
per ISO 639-1.
• LL: Country Code: Two uppercase alphanumeric positions as
per ISO 3166-1 Alpha-2.
example: en-GB

platform*: string
Browser platform
example: Win32

screenColorDepth*: integer($int32)
Screen colour depth

screenHeight*: integer($int32)
Screen height

screenWidth*: integer($int32)
Screen width

timeZone*: integer($int32)
Time zone

userAgent*: string
User agent

acceptHeader*: string
Accept header
}
50
 agentOrderId: string maxLength:200
Agent (payment gateway) order identifier
example: HB3434

purchaseDate*: string ($date-time)

Date on which the purchase was placed in format YYYY-MM-
DDThh:mm[:ss[.nnn]]Z (24-hour format)
example: 2021-02-02T21:46:45.368Z

tmxId: string
Threatmetrix identifier for the operation

pluginName: string maxLength:100

Name of the e-commerce plugin being used by the merchant
example: Zinia

pluginVersion: string maxLength:100

Version of the e-commerce plugin being used by the merchant
example: 1.7

ecommerceName: string maxLength:100

Name of the e-commerce platform being used by the merchant
example: WooCommerce

ecommerceVersion: string maxLength:200

Version of the e-commerce platform being used by the merchant
example: 6.0.1

proprietaryMerchantData:
This object will contain specific information required by each merchant.
However, the information is not “universal”
{
channelId: string maxLength:300
Merchant identifier for BNPL Germany
example: df9789fa99
}

isCustomerTrusted: boolean
Confirm by the merchant that it trusts the customer and a lower scoring could
be applied.
example: false
}

3.4.1.2 Responses
3.4.1.2.1 Status: 201 - Created
Description:
The order has been created successfully and the order identifier is contained in the response.
Schema:
{
orderId: string (uuid)

51
Order identifier
example: 123e4567-e89b-12d3-a456-426614174000

status: string
Order status. You can find more information about order statuses in the Order Status Overview
section of this document.
Enum: CHECKOUT_COMPLETE , CHECKOUT_PENDING , RISK_FRAUD and FAILED
example: CHECKOUT_COMPLETE

paymentMethods:
Payment method information that customers can use to make the payment. This information usually
refers to bank transfers.
{
Required: paymentMethodCode

paymentMethodCode*: string
Payment method internal identifier
Enum: CARD , BANK_TRANSFER and IDEAL
example: BANK_TRANSFER

data:
Additional information regarding the payment method identified by
“paymentMethodTypeCode”.
If paymentMethodTypeCode = BANK_TRANSFER
{
recipient: string
Recipient of the bank transfer
example: Zinia

iban: string
IBAN the bank transfer has been sent to
example: ES3600730100522030000001

bank: string
Bank the bank transfer has been sent to
example: Zinia

bic: string
BIC for the bank transfer
example: OPENESMMXXX

description: string
Reference of the bank transfer. This field will be used to match the payment with the
order
example: DE11WL0ZAU
}
If paymentMethodTypeCode = IDEAL
{
Required: banks

banks*:
List of iDeal Banks
[ {
iDeal Bank Details
52
 Required: code and reference

code*: string
Issuer code
example: 3151

reference*: string
Issuer reference
example: Test Bank
} ]
}
}
}
Example:
{
"orderId": "ceedfd75-e4b9-439f-96ba-3eed4e200c85",
"status": "CHECKOUT_COMPLETE",
"paymentMethods": [
{
"paymentMethodCode": "BANK_TRANSFER",
"data": {
"recipient": "Zinia",
"iban": "ES3600730100522030000001",
"bank": "Zinia",
"bic": "OPENESMMXXX",
"description": "DE112WY8XD"
}
}
]
}

3.4.1.2.2 Status: 400 – Bad Request

Description:
The server cannot process the request due to issues regarding the request body, for example:
• The request body is missing.
• Some of the mandatory fields are missing.
• The request body contains data with the wrong format or invalid values or patterns.
Schema:
{
description:
string example: Invalid request. Please check the data in the request

errorCode: string
example: BAD_REQUEST
}
Example:
This is the generic bad-request response that may appear:
{
"description": "Bad Request, please review it and try again",
"errorCode": "BAD_REQUEST"
}
The description will often contain more details on the fields where the errors have occurred:
{
53
 "description": "field:[purchaseCountry], rejected
value:[iVlc],field:[purchaseCountry], rejected value:[iVlc]",
"errorCode": "BAD_REQUEST"
}

3.4.1.2.3 Status: 401 - Unauthorized

Description:
Either the access token in the “Authorization” header or the API Key in the “ApiKey” header is missing or
invalid.
Schema:
{
description:
string example: The request lacks valid authentication credentials for the
target resource

errorCode: string
example: UNAUTHORIZED
}
Example:
This is the generic unauthorized response:
{
"description": " Unauthorized!",
"errorCode": "UNAUTHORIZED"
}
However, an HTML response may also appear:
<head><title>401 Authorization Required</title></head>
<body>
<center><h1>401 Authorization Required</h1></center>
<hr><center>openresty/1.21.4.1</center>
</body>
</html>

3.4.1.2.4 Status: 403 - Forbidden

Description:
This would happen if your token did not have the rights required to create an order.
Schema:
{
description: string
example: The request has not been authorized

errorCode: string
example: FORBIDDEN
}
Example:
{
"description": " Operation cannot be executed",
"errorCode": " FORBIDDEN"
}

3.4.1.2.5 Status: 422 - Unprocessable entity.

Description:

54
The order cannot be consolidated as some business rules have not been met, for example:
• The OTP is not valid.
• Risk and Fraud failure.
• Other Internal Business Rules.
Schema:
{
description: string
example: User information did not meet the business requirements to execute
the operation

errorCode: string
example: UNPROCESSABLE_ENTITY
}

3.4.1.2.6 Status: 500 - Internal server error

Description:
Something went wrong regarding either Zinia or one of its partners. As such, the order could not be created.
Schema:
{
description: string
example: The request was not fulfilled due to an unexpected condition

errorCode: string
example: GENERIC_ERROR
}
Example:
{
"description": "An error occurred, please try again later",
"errorCode": "GENERIC_ERROR"
}

3.4.2 Order Capture (Fully/Partially)

You will use this endpoint to capture fully or partially the order amount. You should call this endpoint when
the order items have been shipped to the customer and it should be included in the shipping information.
The capture can be carried out by “amount” or by “items” depending on the information received in the
request:
• By amount: A capture by amount will be carried out when the “amount” attribute is informed in the
request.
o If “amount” equals “0”, a full capture will be carried out.
• By items: A capture by items will be carried out when the “orderItems” attribute is informed in the
request.
• If neither the “amount” nor the “orderItems” attribute is informed, a full capture will be carried out.
• If both the “amount” and the “orderItems” attributes are informed, it will be considered a bad
request.

55
3.4.2.1 Parameters
3.4.2.1.1 Path parameters
Name Description

orderId* Required

UUID (uuid)
Order identifier
example: f98b34a0-5fe7-4082-854e-9df1200374eb

3.4.2.1.2 Header parameters

Name Description

Authorization* Required

string
Bearer <accessToken>. Where the accessToken has already been obtained in the
response of the “login” endpoint
example: Bearer EmtSkdWA3Gb37pDiMk1WtWm79eUbiVXsyKDxdoDK6Ic=

ApiKey* Required

string
Encrypted ApiKey obtained using the accessToken and the Merchant API Key
provided by Zinia to the merchant and encoded to Base64 format
example: 5810f3dfffd6497db63b8764ba42c4407f6efded

3.4.2.1.3 Body parameters

Name Description

body* {
shippingDetails:
Details of the shipment
{
trackTraceCode: string
Track trace code
example: 12334324

trackTraceUrl: string
Track trace URL
example: http://tracktrace-url.com/

carrier: string
Carrier’s name
example: SEUR

shippingDate: string
Date when the order was shipped. The format is 'yyyy-mm-dd'. ISO
8601 (Date)
example: 2021-01-01

56
 shippingCost:number
Additional cost due to the shipment type
example: 13
}

reason:string maxLength:300
Reason why the order is being captured
example: Fulfilled by warehouse

invoiceId:string maxLength:300
Invoice identifier
example: AB12345

poNumber:string maxLength:200
Purchase order number
example: 965430823

invoiceUrl:string maxLength:300
Invoice URL
example: http://url/invoice?sid=1234

otpValue:string maxLength:200
This field is only used with “POS” orders. It will contain the code sent to the
customer for the purchase and it will be internally validated.
example: Z36I

amount: number (double)

Amount of the order to be captured. If the amount is equal to 0, a full capture
will be carried out.
If neither the “amount” nor the “orderItems” attribute is informed, a full
capture of the order will be carried out.
example: 30.1

feesAmount: number (double)

Amount of the order that correspond to fees to be captured. For example, the
Order Delivery Fee will be informed in this field.
example: 4.99

orderItems:
List of items from the order that are shipped on this capture.
If neither the “amount” nor the “items” attribute is informed, a full capture of
the order will be carried out.
[ {
Order item to be captured
Required: reference, name and quantity

reference*: string
Item reference
example: 123456

name*: string
Name of the item
example: TV 4k

57
 quantity*: integer (int32)
Quantity of the item to be captured
example: 1
} ]
}

3.4.2.2 Responses
3.4.2.2.1 Status: 201 – Created
Description:
The order has been captured successfully and the capture identifier is contained in the response.
Schema:
{
Required: captureId

captureId*: string
Capture identifier
example: 1234
}
Example:
{
"captureId": "935d5fae-afc3-4a5f-a446-2c9028b311a2_1666962762835"
}

3.4.2.2.2 Status: 400 – Bad Request

Description:
The server cannot process the request due to issues regarding the request body, for example:
• The request body is missing.
• Both the “amount” and the “orderItems” attributes have been included in the request.
• Some of the mandatory fields are not in the request.
• The request body contains data with the wrong format or invalid values or patterns.
Schema:
{
description:
string example: Invalid Request. Please check the data in the request

errorCode: string
example: BAD_REQUEST
}
Example:
This is the generic bad-request response that may appear:
{
"description": "Bad Request, please review it and try again",
"errorCode": "BAD_REQUEST"
}
The description will often contain more details on the fields where the errors have occurred:
{
58
 "description": "field:[amount], rejected value:[557.040]",
"errorCode": "BAD_REQUEST"
}

3.4.2.2.3 Status: 401 - Unauthorized

Description:
Either the access token in the “Authorization” header or the API Key in the “ApiKey” header is missing or
invalid.
Schema:
{
description:
string example: The request lacks valid authentication credentials for the
target resource

errorCode: string
example: UNAUTHORIZED
}
Example:
This is the generic unauthorized response:
{
"description": " Unauthorized!",
"errorCode": "UNAUTHORIZED"
}
However, an HTML response may also appear:
<head><title>401 Authorization Required</title></head>
<body>
<center><h1>401 Authorization Required</h1></center>
<hr><center>openresty/1.21.4.1</center>
</body>
</html>

3.4.2.2.4 Status: 403 - Forbidden

Description:
This would happen if your token did not have the rights required to capture an order.
Schema:
{
description: string
example: The request has not been authorized

errorCode: string
example: FORBIDDEN
}
Example:
{
"description": " Operation cannot be executed",
"errorCode": " FORBIDDEN"
}

3.4.2.2.5 Status: 404 - Not found

Description:

59
The order identifier entered in the path parameter is invalid or does not exist in Zinia for the registered
merchant.
Schema:
{
description: string
example: There is not a current representation for the target resource

errorCode: string
example: NOT_FOUND
}
Example:
{
"description": "Not Found",
"errorCode": "NOT_FOUND"
}

3.4.2.2.6 Status: 409 - Conflict

Description:
The capture cannot be carried out as it may have been duplicated. As the same request has been received
and processed within the last 5 minutes, this request will not be processed to avoid duplicating the
operation.
Schema:
{
description: string
example: Concurrent refund error

errorCode: string
example: CONFLICT
}
Example:
{
"description": "Concurrent capture error",
"errorCode": "CONFLICT"
}

3.4.2.2.7 Status: 422 - Unprocessable entity.

Description:
The order identified by the path parameter cannot be captured as some business rules have not been met,
for example:
• The status of the order means it cannot be captured: ORDER_EXPIRED, ORDER_CANCELLED,
ORDER_SHIPPED or ORDER_REFUNDED.
• The amount of the capture (including feesAmount) to be carried out is higher than the remaining
amount to be captured.
Schema:
{
description: string
example: User information did not meet the business requirements to execute
the operation

60
 errorCode: string
example: UNPROCESSABLE_ENTITY
}
Example:
{
"description": "Unprocessable Entity",
"errorCode": "UNPROCESSABLE_ENTITY"
}

3.4.2.2.8 Status: 500 - Internal server error

Description:
Something went wrong regarding either Zinia or one of its partners. As such, the order could not be captured.
Schema:
{
description: string
example: The request was not fulfilled due to an unexpected condition

errorCode: string
example: GENERIC_ERROR
}
Example:
{
"description": "An error occurred, please try again later",
"errorCode": "GENERIC_ERROR"
}

3.4.3 Cancel Order (Fully/Partially)

This service provides the capability to cancel an order fully or partially. This can only be done before it has
been captured (shipped). Once that has occurred, the “Refund” endpoint should be used.
The cancellation can be carried out by “amount” or by “items” depending on the information received in the
request:
• By amount: A cancellation by amount will be carried out when the “amount” attribute is informed in
the request.
o If “amount” equals 0, a full cancellation will be carried out.
• By Items: A cancellation by items will be carried out when the “orderItems” attribute is informed in
the request.
• If neither the “amount” nor the “orderItems” attribute is informed, a full cancellation will be carried
out.
• If both the “amount” and the “orderItems” attributes are informed, it will be considered a bad
request.

3.4.3.1 Parameters
3.4.3.1.1 Path parameters
Name Description

61
 orderId* Required

UUID (uuid)
Order identifier
example: f98b34a0-5fe7-4082-854e-9df1200374eb

3.4.3.1.2 Header parameters

Name Description

Authorization* Required

string
Bearer <accessToken>. Where the accessToken has already been obtained in the
response of the “login” endpoint
example: Bearer EmtSkdWA3Gb37pDiMk1WtWm79eUbiVXsyKDxdoDK6Ic=

ApiKey* Required

string
Encrypted ApiKey obtained using the accessToken and the Merchant API Key provided
by Zinia to the merchant and encoded to Base64 format
example: 5810f3dfffd6497db63b8764ba42c4407f6efded

3.4.3.1.3 Body parameters

Name Description

body* {
amount: number (double)
Amount of the order to be cancelled. If the amount is equal to 0, a full
cancellation will be executed.
If neither the “amount” nor the “orderItems” attribute is informed, a full
cancellation of the order will be carried out.
example: 30.1

feesAmount: number (double)

Amount of the order that correspond to fees to be captured. For example, the
Order Delivery Fee will be informed in this field.
example: 4.99

orderItems:
List of items from the order that are cancelled on this request.
If neither the “amount” nor the “items” attribute is informed, a full cancellation
of the order will be carried out.
[ {
Order item to be cancelled
Required: reference, name and quantity

reference*: string
Item reference
example: 123456

62
 name*: string
Name of the item
example: TV 4k

quantity*: integer (int32)

Quantity of the item to be cancelled
example: 1
} ]
}

3.4.3.2 Responses
3.4.3.2.1 Status: 201 - Created
Description:
The order has been fully or partially cancelled successfully and the cancellation identifier is contained in the
response.
Schema:
{
Required: cancellationId

cancellationId*: string
Cancellation identifier
example: 1234
}
Example:
{
"cancellationId": "47040"
}

3.4.3.2.2 Status: 400 – Bad Request

Description:
The server cannot process the request due to issues regarding the request body, for example:
• Both the “amount” and the “orderItems” attributes have been included in the request.
• Some of the mandatory fields are not in the request.
• The request body contains data with the wrong format or invalid values or patterns.
Schema:
{
description:
string example: Invalid request. Please check the data in the request

errorCode: string
example: BAD_REQUEST
}
Example:
This is the generic bad-request response that may appear:
{
"description": "Bad Request, please review it and try again",
"errorCode": "BAD_REQUEST"
63
}
The description will often contain more details on the fields where the errors have occurred:
{
"description": " field:[amount], rejected value:[99999999999.99]",
"errorCode": "BAD_REQUEST"
}

3.4.3.2.3 Status: 401 - Unauthorized

Description:
Either the access token in the “Authorization” header or the API Key in the “ApiKey” header is missing or
invalid.
Schema:
{
description:
string example: The request lacks valid authentication credentials for the
target resource

errorCode: string
example: UNAUTHORIZED
}
Example:
This is the generic unauthorized response:
{
"description": " Unauthorized!",
"errorCode": "UNAUTHORIZED"
}
However, an HTML response may also appear:
<head><title>401 Authorization Required</title></head>
<body>
<center><h1>401 Authorization Required</h1></center>
<hr><center>openresty/1.21.4.1</center>
</body>
</html>

3.4.3.2.4 Status: 403 - Forbidden

Description:
This would happen if your token did not have the rights required to cancel an order.
Schema:
{
description: string
example: The request has not been authorized

errorCode: string
example: FORBIDDEN
}
Example:
{
"description": " Operation cannot be executed",
"errorCode": " FORBIDDEN"
}

64
3.4.3.2.5 Status: 404 - Not found
Description:
The order identifier entered in the path parameter is invalid or it does not exist in Zinia for the registered
merchant.
Schema:
{
description: string
example: There is not a current representation for the target resource

errorCode: string
example: NOT_FOUND
}
Example:
{
"description": "Not Found",
"errorCode": "NOT_FOUND"
}

3.4.3.2.6 Status: 409 - Conflict

Description:
The cancellation cannot be carried out as it may have been duplicated. As the same request has been
received and processed within the last 5 minutes, this request will not be processed to avoid duplicating the
operation.
Schema:
{
description: string
example: Concurrent refund error

errorCode: string
example: CONFLICT
}
Example:
{
"description": "Concurrent cancellation error",
"errorCode": "CONFLICT"
}

3.4.3.2.7 Status: 422 - Unprocessable entity.

Description:
The order identified by the path parameter cannot be cancelled as some business rules have not been met,
for example:
• The status of the order means it cannot be captured: ORDER_EXPIRED, ORDER_CANCELLED,
ORDER_SHIPPED or ORDER_REFUNDED.
• The amount of the cancellation (including feesAmount) to be carried out is higher than the remaining
amount of the order.
Schema:
{
description: string

65
 example: User information did not meet the business requirements to execute
the operation

errorCode: string
example: UNPROCESSABLE_ENTITY
}
Example:
{
"description": "Unprocessable Entity",
"errorCode": "UNPROCESSABLE_ENTITY"
}

3.4.3.2.8 Status: 500 - Internal server error

Description:
Something went wrong regarding either Zinia or one of its partners. As such, the order could not be captured.
Schema:
{
description: string
example: The request was not fulfilled due to an unexpected condition

errorCode: string
example: GENERIC_ERROR
}
Example:
{
"description": "An error occurred, please try again later",
"errorCode": "GENERIC_ERROR"
}

3.4.4 Refund Order (Fully/Partially)

This service provides the capability to refund an order fully or partially. Only items or amounts that have
been captured (shipped) can be refunded. If that has not yet occurred, the “cancellations” endpoint should
be used instead.
Refunds can be carried out by “amount” or by “items” depending on the information received in the request:
• By amount: A refund by amount will be carried out when the “amount” attribute is informed in the
request.
o If “amount” equals 0, a full refund will be carried out.
• By items: A refund by items will be carried out when the “orderItems” attribute is informed in the
request.
• If neither the “amount” nor the “orderItems” attribute is informed, a full refund will be carried out.
• If both the “amount” and the “orderItems” attributes are informed, it will be considered a bad
request.

66
3.4.4.1 Parameters
3.4.4.1.1 Path parameters
Name Description

orderId* Required

UUID (uuid)
Order identifier
example: f98b34a0-5fe7-4082-854e-9df1200374eb

3.4.4.1.2 Header parameters

Name Description

Authorization* Required

string
Bearer <accessToken>. Where the accessToken has already been obtained in the
response of the “login” endpoint
example: Bearer EmtSkdWA3Gb37pDiMk1WtWm79eUbiVXsyKDxdoDK6Ic=

ApiKey* Required

string
Encrypted ApiKey obtained using the accessToken and the Merchant API Key
provided by Zinia to the merchant and encoded to Base64 format
example: 5810f3dfffd6497db63b8764ba42c4407f6efded

3.4.4.1.3 Body parameters

Name Description

body* {
amount: number (double)
Amount of the order to be refunded. If the amount is equal to 0, a full refund
will be executed.
If neither the “amount” nor the “orderItems” attribute is informed, a full
refund of the order will be carried out.
example: 30.1

feesAmount: number (double)

Amount of the order that correspond to fees to be captured. For example, the
Order Delivery Fee will be informed in this field.
example: 4.99

orderItems:
List of items from the order that are to be refunded.
If neither the “amount” nor the “orderItems” attribute is informed, a full
refund of the order will be carried out .
[ {
Order item to be refunded
Required: reference, name and quantity
67
 reference*: string
Item reference
example: 123456

name*: string
Name of the item
example: TV 4k

quantity*: integer (int32)

Quantity of the item to be refunded
example: 1
} ]
}

3.4.4.2 Responses
3.4.4.2.1 Status: 201 - Created
Description:
The order has been fully or partially refunded successfully and the refund identifier is contained in the
response.
Schema:
{
Required: refundId

refundId*: string
Refund identifier
example: 1234
}
Example:
{
"refundId": "6995314"
}

3.4.4.2.2 Status: 400 – Bad Request

Description:
The server cannot process the request due to issues regarding the request body, for example:
• The request body is missing.
• Both the “amount” and the “orderItems” attributes have been included in the request.
• Some of the mandatory fields are not in the request.
• The request body contains data with the wrong format or invalid values or patterns.
Schema:
{
description:
string example: Invalid Request. Please check the data in the request

errorCode: string
example: BAD_REQUEST
}
68
Example:
This is the generic bad-request response that may appear:
{
"description": "Bad Request, please review it and try again",
"errorCode": "BAD_REQUEST"
}
The description will often contain more details on the fields where the errors have occurred:
{
"description": " field:[orderItems[0].reference], rejected value:[null]",
"errorCode": "BAD_REQUEST"
}

3.4.4.2.3 Status: 401 - Unauthorized

Description:
Either the access token in the “Authorization” header or the API Key in the “ApiKey” header is missing or
invalid.
Schema:
{
description:
string example: The request lacks valid authentication credentials for the
target resource

errorCode: string
example: UNAUTHORIZED
}
Example:
This is the generic unauthorized response:
{
"description": " Unauthorized!",
"errorCode": "UNAUTHORIZED"
}
However, an HTML response may also appear:
<head><title>401 Authorization Required</title></head>
<body>
<center><h1>401 Authorization Required</h1></center>
<hr><center>openresty/1.21.4.1</center>
</body>
</html>

3.4.4.2.4 Status: 403 - Forbidden

Description:
This would happen if your token did not have the rights required to cancel an order.
Schema:
{
description: string
example: The request has not been authorized

errorCode: string
example: FORBIDDEN
}
Example:
69
{
"description": " Operation cannot be executed",
"errorCode": " FORBIDDEN"
}

3.4.4.2.5 Status: 404 - Not found

Description:
The order identifier entered in the path parameter is invalid or does not exist in Zinia for the registered
merchant.
Schema:
{
description: string
example: There is not a current representation for the target resource

errorCode: string
example: NOT_FOUND
}
Example:
{
"description": "Not Found",
"errorCode": "NOT_FOUND"
}

3.4.4.2.6 Status: 409 - Conflict

Description:
The refund cannot be carried out as it may have been duplicated. As the same request has been received
and processed within the last 5 minutes, this request will not be processed to avoid duplicating the
operation.
Schema:
{
description: string
example: Concurrent refund error

errorCode: string
example: CONFLICT
}
Example:
{
"description": "Concurrent refund error",
"errorCode": "CONFLICT"
}

3.4.4.2.7 Status: 422 - Unprocessable entity.

Description:
The order identified by the path parameter cannot be cancelled as some business rules have not been met,
for example:
• The status of the order means it cannot be captured: ORDER_EXPIRED, ORDER_CANCELLED,
CHECKOUT_COMPLETE (if no partial capture was carried out) or ORDER_REFUNDED.
• The amount of the refund (including feesAmount) to be carried out is higher than the captured
amount of the order.

70
Schema:
{
description: string
example: User information did not meet the business requirements to execute
the operation

errorCode: string
example: UNPROCESSABLE_ENTITY
}
Example:
{
"description": "Unprocessable Entity",
"errorCode": "UNPROCESSABLE_ENTITY"
}

3.4.4.2.8 Status: 500 - Internal server error

Description:
Something went wrong regarding either Zinia or one of its partners. As such, the order could not be captured.
Schema:
{
description: string
example: The request was not fulfilled due to an unexpected condition

errorCode: string
example: GENERIC_ERROR
}
Example:
{
"description": "An error occurred, please try again later",
"errorCode": "GENERIC_ERROR"
}

71
4 Zinia Notification Process

4.1 Overview
The notification process informs you of any change made during the order life cycle.
To receive notifications, Zinia needs to know the endpoint where you want them to be sent. This is done
through the order creation process:

The “noticeUrl” is one of the parameters received in the request body of the checkout order creation (find
more information regarding this request the Checkout section):
noticeUrl: string maxLength:300
URL where notifications of any change in the order will be sent.
example: https://www.your.shop.tld/callback/notice/{transactionId}
Once an order has been updated in Zinia, you will be notified of it through the notification process:

4.2 Which Events Are Notified?

You will be notified of the following status updates:

72
Status Description

CHECKOUT_EXPIRED The order has not been consolidated before the "expirationTime". The
customer did not finalise the Zinia Link-Up process within the predefined
time limit.

CHECKOUT_DECLINED The order consolidation process has failed due either to reasons of risk or
fraud or to it being cancelled by the customer prior to its consolidation.

CHECKOUT_COMPLETE The order has been successfully consolidated.

If a partial cancellation/capture of the order is carried out (one or more items
of the order have been cancelled/shipped by the merchant, but not all of
them, as some are still pending shipment), a notification will be sent with all
the relevant information and the order will remain in the
“CHECKOUT_COMPLETE” status.
If an order was partially captured and a partial/full refund is performed
(some/all of the shipped items are refunded, but given that it regards a partial
capture, some items are still pending shipment), a notification will be sent
with all the relevant information and the order will remain in the
“CHECKOUT_COMPLETE” status.

CHECKOUT_FAILED The order consolidation process has failed due to reasons unrelated to risk,
fraud or a customer cancellation.

ORDER_EXPIRED The order has been successfully consolidated, but none of the items has been
shipped within the deadline.

ORDER_CANCELLED All of the order items have been cancelled by the merchant, so nothing will
be shipped to the customer.
If an order is partial cancelled (one or more items of the order have been
cancelled by the merchant, but not all of them), a notification will be sent
with all the relevant information, but the order will remain in the
“CHECKOUT_COMPLETE” status.

ORDER_SHIPPED All of the items of the order have been shipped to the customer.
If a partial capture (shipment) of the order is carried out (one or more items
of the order have been shipped to the customer, but not all of them), a
notification will be sent with all the relevant information, but the order will
remain in the “CHECKOUT_COMPLETE” status.
If a partial refund of the order is carried out (one or more items of the order
that were shipped to the customer have been returned, but not all of them),
a notification will be sent with all the relevant information and the order will
remain in the “ORDER_SHIPPED” status.

ORDER_REFUNDED All the items of the order that were shipped to the customer have been
returned, so the complete order will have to be refunded.
If a partial refund of the order is carried out (one or more items of the order
that were shipped to the customer have been returned, but not all of them),
a notification will be sent with all the relevant information, but the order will
remain in the “ORDER_SHIPPED” status.

73
 If an order was partially captured and a partial/full refund is carried out
(some/all of the shipped items are refunded, but given that it regards a partial
capture, some items are still pending shipment), a notification will be sent
with all the relevant information, but the order will remain in the
“CHECKOUT_COMPLETE” status.

You can find more information about order statuses in the Order Status Overview section of this document.
You can find the scenarios in which you could receive a notification, based on the order status and the
corresponding action carried out, in the following document:

4.3 How Should You Manage Notifications?

When the status of an order changes, Zinia will notify your server sending a POST request to the
“noticeUrl” provided in the order creation process. We strongly recommend exposing a POST operation.
In your backend, you will need to carry out the following actions:
1. Validate the request (find more information regarding this validation in the Validating Notifications
section).
2. Check the “data.status” field in the request body and update the status of the order in your own
systems (find more information regarding the request body in the Notification Structure (Request
Body) section).
3. Return an HTTP Status Code 200 - OK. This indicates that the notification has been delivered and
acknowledged.

4.4 Validating Notifications

All notifications sent to you will be signed with a JWT. This web token will be sent along with the notification
so that you can verify that it is actually from Zinia.
The JWT will comprise the following claims:
• Iat: Issued at (UTC).
• Jti: Unique identifier of the JWT.
• Payload: SHA-512 of the entire request body of the notification.
JWT example:
{
"Iat": 1666949826,
"Jti": "7287d0ac-98e8-401b-8a7e-34644f0b4168",
"Payload":
"4358fafb26c85d8b92f9b8c69ff2c775d3d6ee86c36ff7ae0e19ba2ee12cf95430c937d5cf4f9a37a3
00b30b5670a48c5a70fdd3c43575bf495944fb7a459f10"
}
The JWT will be encoded with base64 and sent as the header "auth".
You will receive the JWT as a header and the notification itself. In order to check that everything is okay,
carry out the following steps:
Retrieve the JWT from the header ("auth") and check that it has been signed by Zinia using the public key
shared with you during the integration process.
1. Check that the time of the “Iat” claim was within the last 2 minutes.

74
 2. Check that during that timeframe (2 minutes), no other JWT with the same “Jti” has been received
from Zinia (to avoid replay attacks).
3. Retrieve the actual payload of the notification, generate its SHA-512 and compare it with the
“payload” claim of the JWT.
4. If all of the above checks out, you’re good to accept the notification data.

4.5 Notification Structure (Request Body)

The request body sent when POSTing to the "noticeUrl" will contain at least the following information:

Name Description

body* {
Required: notificationId, notificationTimestamp, orderId, merchantOrderId and
data.

notificationId*: string
Unique identifier of the notification
example: f98b34a0-5fe7-4082-854e-9df1200374eb

notificationTimestamp*: string (date-time)

Timestamp when the notification was created. The format is 'YYYY-MM-
DDThh:mm[:ss[.nnn]]Z'. ISO 8601 (Datetime) (24-hour format)
example: 2021-06-28T17:34:01.207Z

notificationSequence: integer (int32)

Indicates the sequence of the notification
example: 1

orderId*: string (uuid)

Order identifier
example: 068df369-13a7-4d47-a564-62f8408bb760

merchantOrderId*: string maxLength:200

Merchant order identifier
example: 900001291100

agentOrderId: string maxLength:200

Agent (payment gateway) order identifier
example: AA3901052327228036

data*:
Notification details
{
Required: status, statusTimestamp and purchaseDate.

operationType: string
Type of operation due to which the notification was triggered.
Enum: CHECKOUT , EXPIRATION , CANCELLATION , SHIP or REFUND .
example: CHECKOUT

operationId: string

75
 If the operation that triggered the notification generated a unique identifier,
this field will contain this information (cancellationId, captureId or refundId).
example: 123456

amount: number (double)

Amount of the order affected by the operation that triggered the notification.
example: 30.1

status*: string
Final status of the order (after the operation that triggered the notification has
been carried out). You can find more information about order statuses in the
Order Status Overview section of this document.
Enum: CHECKOUT_COMPLETE , CHECKOUT_DECLINED , CHECKOUT_FAILED , C
HECKOUT_EXPIRED , ORDER_EXPIRED , ORDER_CANCELLED , ORDER_SHIPPED
or ORDER_REFUNDED .
example: CHECKOUT_COMPLETE

statusTimestamp*: string (date-time)

Timestamp when the order status was updated. The format is 'YYYY-MM-
DDThh:mm[:ss[.nnn]]Z'. ISO 8601 (Datetime) (24-hour format)
example: 2021-06-28T17:33:23.439Z

purchaseDate*: string (date-time)

Timestamp when the order was purchased. The format is 'YYYY-MM-
DDThh:mm[:ss[.nnn]]Z'. ISO 8601 (Datetime) (24-hour format)
example: 2021-01-01T21:46:45.368Z
}
}
Notification example:
{
"notificationId": "2a6d119c-d02e-47de-b659-3ed6dc3a100a",
"notificationTimestamp": "2022-10-28T09:37:05.434377374Z",
"orderId": "8ca0e750-1222-44de-8b55-68f034f53c8c",
"merchantOrderId": "merchantOrderId1666949753",
"agentOrderId": "agentOrderId1666949753",
"data": {
"status": "CHECKOUT_COMPLETE",
"statusTimestamp": "2022-10-28T09:37:05.265274283Z",
"purchaseDate": "2022-10-28T09:35:53.324383Z",
"operationId": "8ca0e750-1222-44de-8b55-68f034f53c8c",
"operationType": "CHECKOUT",
"amount": 242.95
}
}

76
5 Daily Settlement & Reporting
Settlement payments are processed daily for all orders with shipment confirmations and refunds received.
Merchant payments will be issued based on the settlement calendar agreed, taking an additional day or two
to deposit the funds into your bank account.
For each transaction, settlement reports will include:
• Zinia Order Number: Unique order identifier in the Zinia system. It is included in the field
"result.payment_details.order_id" of the checkout operation response body and of the
notifications.
• Merchant Order Number: Your identifier for the order. Order number or another identifier of this
transaction in your system. This was informed as “order_id” in the create-checkout request body
and included as “reference” in the response bodies of all the operations.
• Transaction: Either PAYMENT or REFUND.
• Date Created: Date when the transaction was carried out (YYYY-MM-DD).
• Site: Useful when setting up different e-commerce websites.
• First Name: Customer’s first name.
• Last Name: Customer’s last name.
• Net Amount: Amount of the reported transaction.
• Cost Fee: Incurred cost for the Zinia transaction.
• Currency: Currency in which the transaction was carried out (Alpha-3 Currency Code ISO-4217).
• Processing Date: Date when the transaction was processed (YYYY-MM-DD).

The settlement file will be sent to you via SFTP and/or email. In order to do that, we need you to email the
following information Merchant IT Support ([email protected]):
• Email address where you want the report to be sent.
• SFTP location where you want the file to be stored.
• The credentials to connect to the SFTP. These can be sent in a different email or using any other
secure process.

77