Payment order registration

post https://api.zenki.fi/v1/pay/orders

Service that allows registering a payment order and associating it with a merchant.

Body Params

A JSON structure will be sent that will have the required information to create an order.

version

string

required

length ≤ 9

Data model version, its current value should be v1.0.0.

orderId

string | null

Unique order identifier generated by the merchant. In order to have correct traceability and adequate conversion metrics, it is required to send the OrderId field or the CardId Field.

cartId

string | null

Unique identifier of the shopping cart that allows identifying the purchase of one or more products or services. In order to have correct traceability and adequate conversion metrics, it is required to send the OrderId field or the CardId Field.

type

string

required

Indicates the model for the product delivery or service delivery.

Possible values:

WITH_CARRIER - If a courier is going to be used for the shipment and delivery of the product or service.
WITHOUT_CARRIER - If a courier is not going to be used for the shipment and delivery of the product or service.
MIXED - If a courier is going to be used to send part of the products or services and another part is delivered without using a courier.

countryCodeIso2

string

required

length ≤ 2

Unique country identifier, the definition of the ISO_3166-1 standard is used with 2 characters, see:https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 or https://www.iso.org/iso-3166-country-codes.html

shopper

object | null

Buyer information.

breakdown

object

required

Summary of shopping cart amounts.

items

array of objects

required

Set of products or services considered within the shopping cart.

items*

metadata

Complementary information of the order that the merchant requires to send and inform Zenkipay.

Headers

X-ZENKI-PLUGIN-ID

string

Unique customer identifier used to establish connection with Zenkipay services.

Accept-Language

string

Indicates the language type code for which the content of the services response is returned according to the language reported.

The definition of the ISO_639 standard is used. See: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes or https://www.iso.org/iso-639-language-codes.html

Content-Type

string

required

Content type accepted.

string

required

Accepted formats.

Responses

Response body

object

version

string

required

length ≤ 9

Data model version, its current value should be v1.0.0.

zenkiOrderId

string

required

length ≤ 128

Unique order identifier generated by Zenkipay.

orderId

string

length ≤ 128

Unique order identifier generated by the merchant.

cartId

string

length ≤ 128

Unique identifier of the shopping cart that allows identifying the purchase of one or more products or services.

type

string

required

Indicates the model for the product delivery or service delivery.

Possible values:

WITH_CARRIER - If a courier is going to be used for the shipment and delivery of the product or service.
WITHOUT_CARRIER - If a courier is not going to be used for the shipment and delivery of the product or service.
MIXED - If a courier is going to be used to send part of the products or services and another part is delivered without using a courier.

WITH_CARRIER WITHOUT_CARRIER MIXED

countryCodeIso2

string

required

length ≤ 2

Unique identifier of the country, the definition of the ISO_3166-1 standard is used with 2 characters, see: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 or https://www.iso.org/iso-3166-country-codes.html

status

string

required

Order Status

Possible values:

PENDING - Waiting for the buyer to pay the payment order.
READY4PAY - The buyer has been shown the modal and the order is ready for the buyer to pay for the order with his wallet.
AWAITING_PAYMENT - A first confirmation has been received by the blockchain network, it is waiting to have the required confirmations.
AWAITING_DELIVERY - The payment for the product or service has already been made and the delivery of the product or service is in process.
DELIVERED_SERVICE - The service has already been delivered.
AWAITING_SHIPMENT - The guide for the products has already been uploaded and the shipment is in process.
SHIPPED - The product or service has been shipped.
SHIPMENT_ERROR - There was a problem in the shipping process.
AWAITING_SHOPPER_APPROVAL - Waiting for approval from the buyer to confirm that they have received the product or service.
DISPUTED - The buyer has started a dispute process with the merchant.
PENDING_SHOPPER_RETURN - The merchant is waiting for the buyer to return the product, as a result of the dispute.
REFUNDED - The product or service has been refunded to the buyer.
COMPLETED - The buyer confirms the receipt of the product or service satisfactorily and the exchange of the value of the sale to stable currency has been made only if applicable.
SETTLED - The merchant transaction has been settled.

PENDING READY4PAY AWAITING_PAYMENT AWAITING_DELIVERY DELIVERED_SERVICE AWAITING_SHIPMENT SHIPPED SHIPMENT_ERROR AWAITING_SHOPPER_APPROVAL DISPUTED PENDING_SHOPPER_RETURN REFUNDED COMPLETED SETTLED

createdAt

int64

required

≥ 0

Date and time when Zenkipay received the request to create the order, in milliseconds and UTC format.

The Unix epoch (or Unix time or POSIX time or Unix timestamp) is the number of seconds elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (in ISO 8601: 1970-01-01T00: 00:00Z)

shopper

object | null

Buyer information.

string | null

Merchant-generated buyer's unique identifier.

name

string | null

Buyer name

phone

string | null

Buyer's phone number.

string

required

length ≤ 128

Email of the buyer used to notify the status of his shipping and delivery process.

breakdown

object

required

Summary of shopping cart amounts.

currencyCodeIso3

string

required

length ≤ 5

Unique code of the currency of the country, the definition of the ISO 4217 standard is used with 3 characters, see: https://es.wikipedia.org/wiki/ISO_4217 or https://www.iso.org/iso-4217-currency-codes.html.

totalItemsAmount

double

required

≥ 0

Sum of the total cost of the items (quantity * unitPrice).

shipmentAmount

double

required

≥ 0

Shipping cost, in case of not applying its value must be 0.

subtotalAmount

double

required

≥ 0

Sum of total_items_amount plus shipment_amount.

taxesAmount

double

required

≥ 0

Taxes, if not applied, its value must be 0.

localTaxes_amount

double | null

≥ 0

Local taxes, if not applied, its value must be 0.

importCosts

double | null

≥ 0

Import costs, if not applied, its value must be 0.

discountAmount

double | null

≥ 0

Discount of your merchant, in case of not applying its value must be 0.

additionalCharges

Additional charges, consists of a key/value object that comprises the description of the charge/amount respectively.

grandTotalAmount

double

required

≥ 0

Sum of subtotalAmount, taxesAmount, localTaxesAmount, importCosts, and each value of additionalCharges minus discountAmount.

paymentInfo

object | null

Payment information

exchangeRate

object

required

Summary of the exchange rate used for payment, from local currency to USD

cryptoLove

object

required

Summary of the discount made to the purchase for the use of crypto love.

cryptoPayment

object

required

Summary of the amount paid in crypto currency by the buyer.

settlementInfo

object | null

Order information for settlement to merchant

cryptoSettlement

object

required

The payment detail to be made in cryptocurrency

items

array of objects

required

Set of products or services considered within the shopping cart.

items*

object

externalId

string

length ≤ 128

Unique identifier of the product or service assigned by the merchant.

quantity

int64

required

≥ 0

Total number of products or services of the order of the same type.

unitPrice

double

required

≥ 0

Unit price of the product or service.

name

string

required

length ≤ 128

Short name of the product or service.

description

string | null

Description of the product or service.

type

string

Indicates the model for the product delivery or service delivery.

Possible values:

WITH_CARRIER - If a courier is going to be used for the shipment and delivery of the product or service.
WITHOUT_CARRIER - If a courier is not going to be used for the shipment and delivery of the product or service.

WITH_CARRIER WITHOUT_CARRIER

thumbnailUrl

string | null

Product image URL (thumbnail).

metadata

Complementary information of the product or service that is required to be reported or kept in the Zenkipay system.

metadata

Complementary order information that the merchant requires to send and inform Zenkipay.

dispute

object

Process of a dispute detail.

status

string

required

Dispute current status.

Possible values:

OPEN - The dispute process has started.
REFUND - The dispute process has been closed and a partial or full refund of the full amount of the order has been made.
RESOLVED - The dispute process has been closed without making any refund movement to the buyer.

OPEN REFUND RESOLVED

createdAt

int64

required

≥ 0

Date and time the dispute started, in milliseconds and UTC format.

The Unix epoch (or Unix time or POSIX time or Unix timestamp) is the number of seconds elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (in ISO 8601: 1970-01-01T00: 00:00Z)

resolutionRequestType

string

Support type requested from Zenki staff.

Possible values:

REQUEST_REFUND - Request for support from Zenki staff to make a refund.
REQUEST_CONCILIATED - Request to Zenki staff to reconcile dispute between buyer and merchant.

REQUEST_REFUND REQUEST_CONCILIATED

resolutionRequestAt

int64

≥ 0

Date and time in which the dispute was finalized and a final resolution of the process was given to the buyer, in milliseconds and UTC format.

The Unix epoch (or Unix time or POSIX time or Unix timestamp) is the number of seconds elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (in ISO 8601: 1970-01-01T00: 00:00Z)

claim

object

Claim process detail, when a payment is made and Zenkipay cannot identify it and associate it with the payment order.

reason

string | null

Reason for filing the claim.

status

string

required

Claim current status.

Possible values:

OPEN - The claim process has started.
REFUND - The claim process has been closed and a partial or full refund of the full amount of the order has been made.
RESOLVED - The claim process has been closed without making any reimbursement movement to the buyer, only the payment transaction is associated with the indicated order.
REJECTED - When the claim does not apply, because it tries to associate a payment that does not match the transaction data.

OPEN REFUND RESOLVED REJECTED

createdAt

int64

required

≥ 0

Date and time the clearing started, in milliseconds and UTC format.

The Unix epoch (or Unix time or POSIX time or Unix timestamp) is the number of seconds elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (in ISO 8601: 1970-01-01T00: 00:00Z)

_links

object | null

List of resources related to the order.
The standards used to operate under the HATEOAS model are: https://stateless.group/hal_specification.html, https://datatracker.ietf.org/doc/html/draft-kelly-json-hal and https://www.rfc-editor.org/rfc/rfc8288

The currently supported resources to return within the _link property are:

refund - Returns the refund URI if it exists for the order.

refund

object

Refund detail in case of having any registered to the order.

paymentSignature

string

Signature of the payment order information to display the modal.

Response body

object

requestId

string

required

length ≤ 128

Unique identifier of the error generated by Zenkipay for each request sent to the API.

title

string

required

length ≤ 255

Short description of the error.

errorCode

int64

required

0 to 999

Error code that helps to identify the reason for the problem when processing the request. This code will be based on the HTTP codes currently supported by the specification: https://www.rfc-editor.org/rfc/rfc9110#section-15

category

string

required

Error Category.

Possible values:

FATAL - Any error that forces the service or application to close to prevent data loss (or further data loss). It is reserved for only the most egregious errors and situations where data corruption or loss is guaranteed to have occurred.
SEVERE - Any error that is fatal for the service, but not for the entire application (The service has stopped responding or an operation cannot be executed). These errors will force the intervention of the user (administrator or direct user).
ERROR - Any error that is fatal to the operation, but not to the service or application (cannot open a required file, missing data, etc.). These errors will force the intervention of the user (administrator or direct user).
WARN - Anything that could potentially cause application weirdness, but for which I am self-recovering (Such as switching from a primary to a backup server, retrying an operation, losing secondary data, etc.).
INFO - Informational messages highlighting the app's progress and possibly some minor bug that impacts the experience very little.

FATAL SEVERE ERROR WARN INFO

validationErrors

array of objects | null

Set of validations that did not pass when evaluating the request information.

validationErrors

object

objectName

string

required

length ≤ 255

Object name in the data structure where the error originates.

field

string

required

length ≤ 255

Object field where it presents validation errors.

message

string

required

length ≤ 255

Error description caused by not passing some information validation.

humanMessage

string

required

length ≤ 300

Recommended error message to show buyers, this message is supported for English and Spanish languages.

timestamp

int64

required

≥ 0

Date and time in milliseconds and UTC format to identify the different requests in time, the different ones that have had errors.

The Unix epoch (or Unix time or POSIX time or Unix timestamp) is the number of seconds elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (in ISO 8601: 1970-01-01T00: 00:00Z)

Response body

object

requestId

string

required

length ≤ 128

Unique identifier of the error generated by Zenkipay for each request sent to the API.

title

string

required

length ≤ 255

Short description of the error.

errorCode

int64

required

0 to 999

category

string

required

Error Category.

Possible values:

FATAL - Any error that forces the service or application to close to prevent data loss (or further data loss). It is reserved for only the most egregious errors and situations where data corruption or loss is guaranteed to have occurred.
SEVERE - Any error that is fatal for the service, but not for the entire application (The service has stopped responding or an operation cannot be executed). These errors will force the intervention of the user (administrator or direct user).
ERROR - Any error that is fatal to the operation, but not to the service or application (cannot open a required file, missing data, etc.). These errors will force the intervention of the user (administrator or direct user).
WARN - Anything that could potentially cause application weirdness, but for which I am self-recovering (Such as switching from a primary to a backup server, retrying an operation, losing secondary data, etc.).
INFO - Informational messages highlighting the app's progress and possibly some minor bug that impacts the experience very little.

FATAL SEVERE ERROR WARN INFO

validationErrors

array of objects | null

Set of validations that did not pass when evaluating the request information.

validationErrors

object

objectName

string

required

length ≤ 255

Object name in the data structure where the error originates.

field

string

required

length ≤ 255

Object field where it presents validation errors.

message

string

required

length ≤ 255

Error description caused by not passing some information validation.

humanMessage

string

required

length ≤ 300

Recommended error message to show buyers, this message is supported for English and Spanish languages.

timestamp

int64

required

≥ 0

Date and time in milliseconds and UTC format to identify the different requests in time, the different ones that have had errors.

The Unix epoch (or Unix time or POSIX time or Unix timestamp) is the number of seconds elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (in ISO 8601: 1970-01-01T00: 00:00Z)

Response body

object

requestId

string

required

length ≤ 128

Unique identifier of the error generated by Zenkipay for each request sent to the API.

title

string

required

length ≤ 255

Short description of the error.

errorCode

int64

required

0 to 999

category

string

required

Error Category.

Possible values:

FATAL - Any error that forces the service or application to close to prevent data loss (or further data loss). It is reserved for only the most egregious errors and situations where data corruption or loss is guaranteed to have occurred.
SEVERE - Any error that is fatal for the service, but not for the entire application (The service has stopped responding or an operation cannot be executed). These errors will force the intervention of the user (administrator or direct user).
ERROR - Any error that is fatal to the operation, but not to the service or application (cannot open a required file, missing data, etc.). These errors will force the intervention of the user (administrator or direct user).
WARN - Anything that could potentially cause application weirdness, but for which I am self-recovering (Such as switching from a primary to a backup server, retrying an operation, losing secondary data, etc.).
INFO - Informational messages highlighting the app's progress and possibly some minor bug that impacts the experience very little.

FATAL SEVERE ERROR WARN INFO

validationErrors

array of objects | null

Set of validations that did not pass when evaluating the request information.

validationErrors

object

objectName

string

required

length ≤ 255

Object name in the data structure where the error originates.

field

string

required

length ≤ 255

Object field where it presents validation errors.

message

string

required

length ≤ 255

Error description caused by not passing some information validation.

humanMessage

string

required

length ≤ 300

Recommended error message to show buyers, this message is supported for English and Spanish languages.

timestamp

int64

required

≥ 0

Date and time in milliseconds and UTC format to identify the different requests in time, the different ones that have had errors.

The Unix epoch (or Unix time or POSIX time or Unix timestamp) is the number of seconds elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (in ISO 8601: 1970-01-01T00: 00:00Z)

Response body

object

requestId

string

required

length ≤ 128

Unique identifier of the error generated by Zenkipay for each request sent to the API.

title

string

required

length ≤ 255

Short description of the error.

errorCode

int64

required

0 to 999

category

string

required

Error Category.

Possible values:

FATAL - Any error that forces the service or application to close to prevent data loss (or further data loss). It is reserved for only the most egregious errors and situations where data corruption or loss is guaranteed to have occurred.
SEVERE - Any error that is fatal for the service, but not for the entire application (The service has stopped responding or an operation cannot be executed). These errors will force the intervention of the user (administrator or direct user).
ERROR - Any error that is fatal to the operation, but not to the service or application (cannot open a required file, missing data, etc.). These errors will force the intervention of the user (administrator or direct user).
WARN - Anything that could potentially cause application weirdness, but for which I am self-recovering (Such as switching from a primary to a backup server, retrying an operation, losing secondary data, etc.).
INFO - Informational messages highlighting the app's progress and possibly some minor bug that impacts the experience very little.

FATAL SEVERE ERROR WARN INFO

validationErrors

array of objects | null

Set of validations that did not pass when evaluating the request information.

validationErrors

object

objectName

string

required

length ≤ 255

Object name in the data structure where the error originates.

field

string

required

length ≤ 255

Object field where it presents validation errors.

message

string

required

length ≤ 255

Error description caused by not passing some information validation.

humanMessage

string

required

length ≤ 300

Recommended error message to show buyers, this message is supported for English and Spanish languages.

timestamp

int64

required

≥ 0

Date and time in milliseconds and UTC format to identify the different requests in time, the different ones that have had errors.

The Unix epoch (or Unix time or POSIX time or Unix timestamp) is the number of seconds elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (in ISO 8601: 1970-01-01T00: 00:00Z)

Response body

object

requestId

string

required

length ≤ 128

Unique identifier of the error generated by Zenkipay for each request sent to the API.

title

string

required

length ≤ 255

Short description of the error.

errorCode

int64

required

0 to 999

category

string

required

Error Category.

Possible values:

FATAL - Any error that forces the service or application to close to prevent data loss (or further data loss). It is reserved for only the most egregious errors and situations where data corruption or loss is guaranteed to have occurred.
SEVERE - Any error that is fatal for the service, but not for the entire application (The service has stopped responding or an operation cannot be executed). These errors will force the intervention of the user (administrator or direct user).
ERROR - Any error that is fatal to the operation, but not to the service or application (cannot open a required file, missing data, etc.). These errors will force the intervention of the user (administrator or direct user).
WARN - Anything that could potentially cause application weirdness, but for which I am self-recovering (Such as switching from a primary to a backup server, retrying an operation, losing secondary data, etc.).
INFO - Informational messages highlighting the app's progress and possibly some minor bug that impacts the experience very little.

FATAL SEVERE ERROR WARN INFO

validationErrors

array of objects | null

Set of validations that did not pass when evaluating the request information.

validationErrors

object

objectName

string

required

length ≤ 255

Object name in the data structure where the error originates.

field

string

required

length ≤ 255

Object field where it presents validation errors.

message

string

required

length ≤ 255

Error description caused by not passing some information validation.

humanMessage

string

required

length ≤ 300

Recommended error message to show buyers, this message is supported for English and Spanish languages.

timestamp

int64

required

≥ 0

Date and time in milliseconds and UTC format to identify the different requests in time, the different ones that have had errors.

The Unix epoch (or Unix time or POSIX time or Unix timestamp) is the number of seconds elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (in ISO 8601: 1970-01-01T00: 00:00Z)

Response body

object

requestId

string

required

length ≤ 128

Unique identifier of the error generated by Zenkipay for each request sent to the API.

title

string

required

length ≤ 255

Short description of the error.

errorCode

int64

required

0 to 999

category

string

required

Error Category.

Possible values:

FATAL - Any error that forces the service or application to close to prevent data loss (or further data loss). It is reserved for only the most egregious errors and situations where data corruption or loss is guaranteed to have occurred.
SEVERE - Any error that is fatal for the service, but not for the entire application (The service has stopped responding or an operation cannot be executed). These errors will force the intervention of the user (administrator or direct user).
ERROR - Any error that is fatal to the operation, but not to the service or application (cannot open a required file, missing data, etc.). These errors will force the intervention of the user (administrator or direct user).
WARN - Anything that could potentially cause application weirdness, but for which I am self-recovering (Such as switching from a primary to a backup server, retrying an operation, losing secondary data, etc.).
INFO - Informational messages highlighting the app's progress and possibly some minor bug that impacts the experience very little.

FATAL SEVERE ERROR WARN INFO

validationErrors

array of objects | null

Set of validations that did not pass when evaluating the request information.

validationErrors

object

objectName

string

required

length ≤ 255

Object name in the data structure where the error originates.

field

string

required

length ≤ 255

Object field where it presents validation errors.

message

string

required

length ≤ 255

Error description caused by not passing some information validation.

humanMessage

string

required

length ≤ 300

Recommended error message to show buyers, this message is supported for English and Spanish languages.

timestamp

int64

required

≥ 0

Date and time in milliseconds and UTC format to identify the different requests in time, the different ones that have had errors.

The Unix epoch (or Unix time or POSIX time or Unix timestamp) is the number of seconds elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (in ISO 8601: 1970-01-01T00: 00:00Z)

201Order created.

400Expected order parameter.

403Access denied.

404Resource not found.

406Headers not accepted.

428Parameter name cannot be found.

500Internal Server Error.