NAV
cURL

General information

This documentation is a concise reference manual containing instructions about how to effectively use and integrate with Zero21 API.

Supported Payment Options

Payment Option Supported Countries Processing Currency
CPay Worldwide USDC

Supported Currencies

Transactions can be submitted in any FIAT currency. Submitted amount will be converted at the time of the transaction.

Authentication

Authentication to the API occurs via HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password.

Keys are defined per website. You can manage your keys in your Merchant Tool.

For API integration you need to use Secret Key.

Test and live keys are supported for an easy switch from test to live mode. The test key works in the exact same way as the live key, but doesn’t do live transactions.

Pagination

curl https://api.zero21.eu/api/transactions/?limit=<LIMIT>&offset=<OFFSET> \
-u <WEBSITE_SECRET_KEY>:

The above command returns JSON structured like this:

{
  "transactions": [
    {
      "id": "trn_345812d991",
      "mode": "Test",
      "status": "Created",
      "customer": {
        "id": "cus_a8e955b73cbd45348",
        "mode": "Test",
        "firstName": "Jonathan",
        "lastName": "Scott",
        "email": "ligula.consectetuer.rhoncus@Fusce.com",
        "birthDate": "06/15/1990",
        "country": "CY",
        "created": "2016-02-25T08:51:37.823Z"
      },
      "payment": {
        "id": "pay_b1f063633853412eb",
        "mode": "Test",
        "customerId": "cus_a8e955b73cbd45348",
        "paymentOption": "cpay",
        "holder": "Jonathan Scott",
        "created": "2016-02-25T08:51:37.743Z"
      },
      "amount": 2499,
      "currency": "EUR",
      "merchantPassThruData": "7716902",
      "created": "2016-02-25T08:51:37.823Z"
    },
    {
      "id": "trn_ed77df2dcf",
      "mode": "Test",
      "status": "Created",
      "customer": {
        "id": "cus_4b08ee7682cb4afd8",
        "mode": "Test",
        "firstName": "ralf",
        "lastName": "Wright",
        "email": "eu@Namnullamagna.com",
        "birthDate": "05/20/1992",
        "country": "CY",
        "created": "2016-02-25T08:51:37.103Z"
      },
      "payment": {
        "id": "pay_37636b775d474cd4a",
        "mode": "Test",
        "customerId": "cus_4b08ee7682cb4afd8",
        "paymentOption": "cpay",
        "holder": "ralf Wright",
        "created": "2016-02-25T08:51:37.073Z"
      },
      "amount": 2900,
      "currency": "EUR",
      "merchantPassThruData": "7718021",
      "created": "2016-02-25T08:51:37.103Z"
    }
  ],
  "pagination": {
    "offset": 10,
    "limit": 2,
    "count": 2504
  }
}

Some responses can have large collections of data. We support pagination using offset and limit parameters.

By default, when you search for something, we will return all the matching records. However, you can use a parameter called limit to tell the API how many records you want to return all at once.

GET https://api.zero21.eu/api/transactions?limit=5

To get all the records you need to use another parameter along with limit called offset. This parameter tells the API where to start returning records from the entire set of results. If you don’t include this parameter, the default is to start at record number 0 and then return the number of records specified with the ‘limit’ parameter.

GET https://api.zero21.eu/api/transactions?limit=5&offset=10

In API response, you will receive information about the offset, limit and count (for total record count).

Example: "pagination": { "offset": 10, "limit": 5, "count": 2504 }

Test mode

The live and test environments each have a different API key pair. Both Live and Test APIs use the same API endpoint and both environments work in the same way, but in Test mode only test networks are visible.

Support

If you require support with the integration, or you have any questions or need assistance of any kind, feel free to reach out to us by opening a support ticket.

 

 

 

 

 

Transactions

Attributes ↓

Parameter Type Description Requirement
customer Customer object Customer object Conditional, either Customer or customerId is required
customerId string Customer identifier Conditional, either Customer or customerId is required
payment Payment object Payment object Required
amount integer The used amount (calculated in cents) Required
currency string ISO 4217 formatted currency code Required
merchantPassThruData string Merchant’s identification Optional
merchantTransactionId string The unique identifier for a payment provided by the merchant Optional
description string Description Optional
ipAddress string Customer’s IP address Required
returnUrl string URL that customer is redirected to after successful payment Required
cancelUrl string URL that customer is redirected to on aborted payment Required

 

 

Creating a Transaction ↓

Every single payment request in the API will generate a Transaction. Each Transaction is uniquely identified by Transaction ID. To obtain details about a Transaction you need to make a separate GET request.

Using Payment Object

When creating a transaction, you can either send full payment object body each time transaction is made, or you can create payment object once and then reuse it when creating new transactions. Payment object can be reused multiple times.

Creating Payment Object
curl https://api.zero21.eu/api/payments -u \
<WEBSITE_SECRET_KEY>:  -H "Content-Type:application/json" -X POST -d '
{
"holder": "John Doe",
"paymentOption":"cpay"
}'

The above command returns JSON structured like this:

{
  "id": "pay_4c03abe649914b1a9",
  "mode": "Test",
  "paymentOption": "cpay",
  "holder": "John Doe",
  "created": "2016-09-09T03:40:32.7497062Z",
  "ipaddress": "123.1.1.1"
}

To create paymentObject, using Secret API key you must submit required payment object parameters. Required paremeters for payment object vary depending on payment option used.

In response, paymentObject id will be sent.

 

Creating transaction using Payment Object
curl https://api.zero21.eu/api/transactions -u \
<WEBSITE_SECRET_KEY>:  -H "Content-Type:application/json" -X POST -d '
{
  "currency": "EUR",
  "amount": 500,
  "ipaddress": "123.1.1.1",
  "paymentid":"pay_4c03abe649914b1a9",
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@doe.com",
    "birthDate": "06/15/1990",
    "country": "DE"
  },
  "redirectUrls": {
    "returnUrl": "https://developers.zero21.eu/returnpages/success.html",
    "cancelUrl": "https://developers.zero21.eu/returnpages/failure.html"
  }
}'

The above command returns JSON structured like this:

{
  "id": "trn_d12209838b",
  "mode": "Test",
  "status": "Pending",
  "customer": {
    "id": "cus_de0636cef44540a4a",
    "mode": "Test",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@doe.com",
    "birthDate": "06/15/1990",
    "fullName": "John Doe",
    "country": "CY",
    "created": "2016-03-17T05:17:58.0438821Z"
  },
  "payment": {
    "id": "pay_4c03abe649914b1a9",
    "mode": "Test",
    "paymentOption": "cpay",
    "holder": "John Doe",
    "created": "2016-03-17T05:17:58.0108663Z"
  },
  "amount": 500,
  "currency": "EUR",
  "created": "2016-03-17T05:17:58.0388728Z",
  "redirectUrls": {
    "returnUrl": "https://developers.zero21.eu/returnpages/success.html",
    "cancelUrl": "https://developers.zero21.eu/returnpages/failure.html"
  },
  "ipaddress": "123.1.1.1",
  "redirectUrl": "http://mybankingsite.com/hRedirection.aspx?transaction_id=trn_1a5f5e0c97"
}

Once payment object has been created, you can create a transaction using generated "paymentid" instead of sending the whole payment object.

CPay

curl https://api.zero21.eu/api/transactions -u \
<WEBSITE_SECRET_KEY>:  -H "Content-Type:application/json" -X POST -d '
{
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@doe.com",
    "birthDate": "06/15/1990",
    "country": "CY"
  },
  "payment": {
    "paymentOption": "cpay",
    "holder": "John Doe"
  },
  "amount": 100,
  "currency": "EUR",
  "ipaddress": "123.1.1.1",
  "redirectUrls": {
    "returnUrl": "https://developers.zero21.eu/returnpages/success.html",
    "cancelUrl": "https://developers.zero21.eu/returnpages/failure.html"
  }
}'

The above command returns JSON structured like this:

{
  "id": "trn_1a5f5e0c97",
  "mode": "Test",
  "status": "Pending",
  "customer": {
    "id": "cus_bf682a6c051145a09",
    "mode": "Test",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@doe.com",
    "birthDate": "06/15/1990",
    "fullName": "John Doe",
    "country": "CY",
    "created": "2016-03-25T13:51:04.8497785Z"
  },
  "payment": {
    "id": "pay_ffd25121f84e4d249",
    "mode": "Test",
    "paymentOption": "cpay",
    "holder": "John Doe",
    "created": "2016-03-25T13:51:04.7717784Z",
    "ipaddress": "123.1.1.1"
  },
  "amount": 100,
  "currency": "EUR",
  "created": "2016-03-25T13:51:04.8497785Z",
  "redirectUrls": {
    "returnUrl": "https://developers.zero21.eu/returnpages/success.html",
    "cancelUrl": "https://developers.zero21.eu/returnpages/failure.html"
  },
  "ipaddress": "123.1.1.1",
  "redirectUrl": "http://mybankingsite.com/hRedirection.aspx?transaction_id=trn_1a5f5e0c97"
}

CUSTOMER OBJECT

Parameter Type Description Requirement
firstName string Customer’s First Name Mandatory
lastName string Customer’s Last Name Mandatory
email string Customer’s Email Mandatory
address string Customer’s address - Street Name Optional
address2 string Customer’s address - Street Number Optional
city string Customer’s city Optional
zip string Customer’s city Postal Code Optional
state string Customer’s state - 2 letter code Optional
country string Customer’s country - ISO 3166-1 country Code Mandatory
birthDate date Customer’s birthday - MM/DD/YYYY Mandatory
phone string Customer’s phone Number Optional

PAYMENT OBJECT

Parameter Type Description Requirement
paymentOption string cpay Mandatory
holder string Customer’s First and Last Name Mandatory

Retrieving Transaction ↓

 curl https://api.zero21.eu/api/transactions/{Id} \
 -u <WEBSITE_SECRET_KEY>:

The above command returns JSON structured like this:

{
    "id": "trn_326cf8bab3a742",
    "mode": "Live",
    "status": "Funded",
    "customer": {
        "id": "cus_0fe9bf220263461c9",
        "mode": "Live",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@doe.com",
        "birthDate": "06/15/1990",
        "created": "2020-10-05T10:25:32.677Z"
    },
    "paymentId": "pay_b010589bb3f944a48",
    "payment": {
        "id": "pay_b010589bb3f944a48",
        "mode": "Live",
        "customerId": "cus_0fe9bf220263461c9",
        "paymentOption": "cpay",
        "holder": "John Doe",
        "created": "2020-10-05T10:25:32.56Z",
        "ipAddress": "77.46.149.145"
    },
    "amount": 100,
    "currency": "EUR",
    "created": "2020-10-05T10:25:32.67Z",
    "ipAddress": "77.46.149.145"
}

Retrieves the details of a transaction using the identifier of the transaction (transaction id).

ATTRIBUTES

Parameter Type Description
id string Unique identifier of the transaction
Request example

GET https://api.zero21.eu/api/transactions/trn_326cf8bab3a742

RESPONSE ATTRIBUTES
Parameter Type Description
id string Unique identifier for this transaction
mode Enum (Test, Live) Indication if the transaction was created using Test or Live keys
status Enum Identifies transaction status
customer customer object Customer Object
paymentId string Unique identifier for payment
payment payment object Payment Object
amount integer Transaction amount
currency string Transaction currency
created string UTC creation date
ipAddress string Customer IP address

Retrieve Refund

curl https://api.zero21.eu/api/transactions/{transactionId}/refunds/{refundId} \
-u <WEBSITE_SECRET_KEY>:

The above command returns JSON structured like this:

{
    "id": "ref_f811756",
    "mode": "Test",
    "amount": 100,
    "currency": "USD",
    "originalTransactionId": "trn_00dc520",
    "originalTransaction": {
        "id": "trn_00dc520",
        "mode": "Test",
        "status": "Refunded",
        "customer": {
            "id": "cus_0635336b935f4d14b",
            "mode": "Test",
            "firstName": "Jane",
            "lastName": "Doe",
            "email": "jane@doe.com",
            "birthDate": "06/15/1990",
            "country": "CY",
            "created": "2015-06-22T12:07:18.323Z"
        },
        "payment": {
            "id": "pay_55e66facd4874733a",
            "mode": "Test",
            "customerId": "cus_0635336b935f4d14b",
            "paymentOption": "cpay",
            "holder": "John Doe",
            "created": "2015-06-22T12:07:17.71Z"
        },
        "amount": 100,
        "currency": "USD",
        "created": "2015-06-22T12:07:18.32Z"
    },
    "created": "2015-06-23T12:46:10.917Z",
    "status": "Approved"
}

Retrieves the details of an existing refund.

REQUEST

GET https://api.zero21.eu/api/{transactionId}/refunds/{refundId}

List Transactions ↓

 -u <WEBSITE_SECRET_KEY>:
 curl https://api.zero21.eu/api/transactions/
 curl https://api.zero21.eu/api/transactions/?{offset}&{Limit}&{startDate}&{endDate}

The above command returns JSON structured like this:

{
  "transactions": [
    {
      "id": "trn_2bbcd34688",
      "mode": "Test",
      "status": "Pending",
      "customer": {
        "id": "cus_b9c6a32127724ecea",
        "mode": "Test",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@doe.com",
        "birthDate": "06/15/1990",
        "fullName": "John Doe",
        "country": "CY",
        "created": "2016-03-25T14:04:41.763Z"
      },
      "payment": {
        "id": "pay_f633ab65f86b4dac8",
        "mode": "Test",
        "customerId": "cus_b9c6a32127724ecea",
        "paymentOption": "cpay",
        "holder": "John Doe",
        "created": "2016-03-25T14:04:41.687Z",
        "ipAddress": "123.1.1.1"
      },
      "amount": 23,
      "currency": "EUR",
      "merchantPassThruData": "order_242444",
      "created": "2017-08-25T14:04:41.763Z"
    },
    {
      "id": "trn_1a5f5e0c97",
      "mode": "Test",
      "status": "Pending",
      "customer": {
        "id": "cus_bf682a6c051145a09",
        "mode": "Test",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@doe.com",
        "birthDate": "06/15/1990",
        "fullName": "John Doe",
        "country": "CY",
        "created": "2016-03-25T13:51:04.85Z"
      },
      "payment": {
        "id": "pay_ffd25121f84e4d249",
        "mode": "Test",
        "customerId": "cus_bf682a6c051145a09",
        "paymentOption": "cpay",
        "holder": "Piet Saar",
        "created": "2016-03-25T13:51:04.773Z",
        "ipAddress": "123.1.1.1"
      },
      "amount": 1700,
      "currency": "EUR",
      "merchantPassThruData": "ideal",
      "created": "2017-08-26T13:51:04.85Z"
    }
  ]

This API call returns a list of transactions created in a particular timeframe.

Request examples

GET https://api.zero21.eu/api/transactions/

GET https://api.zero21.eu/api/transactions/?offset=1&Limit=1000&startDate=2017-08-07T11:14:09.5621581Z&endDate=2018-06-18T11:14:09.5621581Z

REQUEST ATTRIBUTES

Parameter Type Description
offset string Number of pages
Limit string Upper Limit for transactions in response
startDate date Created FROM date and time
endDate date Created TO date and time

RESPONSE ATTRIBUTES

Parameter Type Description
id string Unique identifier for the transaction
mode Enum (Test, Live) Indication if the transaction was created using Test or Live keys
status Enum Identifies transaction status
customer customer object Customer object
payment payment object Payment Object
amount integer Transaction amount
currency string ISO 4217 formatted currency code
created string UTC creation date

Refund a Transaction

curl https://api.zero21.eu/api/transactions/{transactionId}/refunds \
-u <WEBSITE_SECRET_KEY>:  -H "Content-Type:application/json" -X POST -d '
{
    "reason": "FRAUD"
}'

The above command returns JSON structured like this:

{
    "transactionId": "trn_00dc520",
    "reason": "FRAUD",
    "message": "Your refund request has been accepted. Once processed, you will receive a webhook notification."
}

Initiate refund for a transaction that has been previously funded.

ATTRIBUTES

Parameter Type Description
reason string Reason for the refund, from predefined list
REFUND REASONS
Parameter Description
END_USER_ERROR End user error
FRAUD Fraud
UNSATISFIED_CUSTOMER Unsatisfied customer
INVALID_TRANSACTION Invalid transaction
MERCHANT_REQUEST Merchant request
MANAGEMENT_REQUEST Management request
DUPLICATED Duplicated

REQUEST

POST https://api.zero21.eu/api/transactions/{transactionId}/refunds

Customers

Create a Customer

curl https://api.zero21.eu/api/customers -u \
<WEBSITE_SECRET_KEY>:  -H "Content-Type:application/json" -X POST -d '
{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@doe.com",
  "birthDate": "06/15/1990",
  "address": "Rutledge Ave 409",
  "city": "Folsom",
  "zip": "19033",
  "country": "US",
  "state":"PA",
  "phone": "55555555555"
}'

The above command returns JSON structured like this:

{
  "id": "cus_bd838e3611d34d598",
  "mode": "Test",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@doe.com",
  "birthDate": "06/15/1990",
  "address": "Rutledge Ave 409",
  "city": "Folsom",
  "zip": "19033",
  "country": "US",
  "state": "PA",
  "phone": "55555555555",
  "fullName": "John Doe",
  "created": "2016-03-24T15:19:10.7800694Z"
}

Customers can be created individually by you or they will be automatically generated with the transaction if there is no customer ID transmitted.

Attributes

Parameter Type Description Requirement
firstName string First name Mandatory
lastName string Last name Mandatory
email string Email Mandatory
birthDate date (MM/dd/yyyy) Date of Birth Mandatory
address string address Optional
city string city Optional
zip string city ZIP code Optional
country string country Optional
state string state Optional
phone string phone number Optional

Retrieve a Customer

Retrieves the details of an existing customer.

curl https://api.zero21.eu/api/customers/{id} \
-u <WEBSITE_SECRET_KEY>:  -H "Content-Type:application/json" -X GET -d '

The above command returns JSON structured like this:

{
  "id": "cus_bd838e3611d34d598",
  "mode": "Test",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@doe.com",
  "birthDate": "06/15/1990",
  "address": "Rutledge Ave 409",
  "city": "Folsom",
  "zip": "19033",
  "country": "US",
  "state": "PA",
  "phone": "55555555555",
  "created": "2016-03-24T15:19:10.7800694Z"
}

Attributes

Parameter Type Description Requirement
id string Customer’s id Mandatory

List Customers

Returns a list of your customers.

curl https://api.zero21.eu/api/customers \
-u <WEBSITE_SECRET_KEY>:  -H "Content-Type:application/json" -X GET -d

The above command returns JSON structured like this:

{
    "customers": [
        {
            "id": "cus_7f0724f3b1d745d49",
            "mode": "Test",
            "firstName": "Jane",
            "lastName": "Doe",
            "email": "jane@doe.com",
            "birthDate": "06/15/1990",
            "country": "DE",
            "created": "2015-06-24T11:46:35.303Z"
        },
        {
            "id": "cus_15b154da474247dbb",
            "mode": "Test",
            "firstName": "John",
            "lastName": "Doe",
            "email": "john@doe.com",
            "birthDate": "01/20/1999",
            "address": "Rutledge Ave 409",
            "city": "Folsom",
            "zip": "19033",
            "country": "US",
            "phone": "55555555555",
            "created": "2015-06-24T12:28:06.527Z"
        }
    ]
}

Webhooks

Sample data in JSON

{
  "id": "evt_1148cf19885841bdb2dddb",
  "type": "transaction.pending",
  "resourceName": "Transaction",
  "resource": {
    "id": "trn_a699c13ebe2c43",
    "mode": "Live",
    "status": "Pending",
    "customer": {
      "id": "cus_04263bb1c41a433eb",
      "mode": "Live",
      "firstName": "John",
      "lastName": "Doe",
      "email": "johndoe@example.com",
      "country": "DE",
      "birthDate": "06/15/2000",
      "fullName": "John Doe",
      "created": "2026-06-24T11:47:03.316236Z"
    },
    "payment": {
      "id": "pay_e836f239cd7541629",
      "mode": "Live",
      "paymentOption": "CPay",
      "holder": "John Doe",
      "created": "2026-06-24T11:47:03.2781547Z",
      "ipAddress": "123.1.1.1"
    },
    "amount": 500,
    "currency": "USD",
    "created": "2026-06-24T11:47:03.3023238Z",
    "redirectUrls": {
      "returnUrl": "https://developers.zero21.eu/returnpages/success.html",
      "cancelUrl": "https://developers.zero21.eu/returnpages/failure.html"
    },
    "ipAddress": "123.1.1.1"
  },
  "created": "2026-06-24T11:47:03.4438609Z"
}

With webhooks, we give you the possibility to react automatically to certain events which happen within our system. A webhook endpoint is basically a URL where we send an HTTP POST request to, every time one of the events attached to that webhook is triggered.

Event Code Description
customer.created The customer object has been created in the system.
transaction.pending The transaction has been created in the system and is awaiting an action.
transaction.aborted A status indicating that a transaction has been canceled by the customer during confirmation on his e-banking account page.
transaction.approved A transaction that has been accepted by an acquirer.
transaction.funded A transaction that has been accepted by an acquirer and has passed the System defined settlement guidelines
transaction.declined A status indicating that a transaction has been rejected prior to receiving an approved status.
transaction.isf A status indicating that there were insufficient funds in the customer’s account to settle a transaction.
refund.pending Refund of the transaction is processed by the System, but not yet refunded.
refund.succeeded A status indicating that funds were reversed for a transaction, and the amount or a portion of this amount was returned back to the customer.
refund.declined Refund of the transaction is declined.

To confirm transaction status, you can use Retrieve a transaction API call.

Errors

Atributes

type Description
invalid_parameter_error Invalid paremeter was sent
payment_error Transaction failed to be created due to payment issue
api_error API errors

List of errors for invalid_paremeter_error

Code Message Status Code
api_keys_not_provided API keys are not provided 401
invalid_api_keys Invalid API key %s 401
invalid_object_sent Object is not sent or invalid object is sent 400
missing_required_parameter Missing required parameter %s 400
invalid_parameter_error Invalid parameter %s 400
disabled_website Disabled website 400
invalid_website Invalid website 400
invalid_transaction_id Invalid transaction 400
invalid_original_transaction_id Invalid transaction 400
invalid_payment_id Invalid payment id 400
invalid_customer_id Invalid customer id 400
invalid_reason Invalid reason 400
provide_payment_or_token Provide either payment object or token 400
provide_customer_or_customerid Provide either customer object or customerid 400
invalid_payment_option Invalid payment option 400
invalid_currency Invalid currency 400
negative_number Must be positive number 400
email_domain_black_listed Email domain is found on the black list 400
information_on_black_list Information sent on the transaction are found on the blacklist 400
customer_black_listed Customer is found on the black list 400
number_of_transaction_exceeded_limit Number of the transactions exceeded limit 400
volume_of_transaction_exceeded_limit Volume of the transactions exceeded limit 400
max_transaction_amount Volume of the transactions is higher then maximum limit 400
min_transaction_amount Volume of the transactions is lower then minimum limit 400
invalid_country Invalid country 400
parameter_can_have_100_characters_maximum Parameter %s can have 100 characters maximum. 400
payment_option_is_not_active Payment option is not active. 503
customer_reached_payment_limit Customer reached the payment limit for the period. 400
currency_is_not_active_in_system Currency is not active in the system. 400

List of errors for payment_error

Code Message Status Code
refund_not_supported Refund is not supported 402
transaction_can_not_be_refunded The transaction can not be refunded 402
refund_already_sent Refund already sent 402
customer_must_be_at_least_18_years_old Customer must be at least 18 years old 402
transaction_timeout Timeout 408
transaction_aborted Transaction aborted by user. 400

List of errors for api_error

Code Message Status Code
api_error API Error 402
acquirer_down Acquirer Down 402
statuscode Description
200 OK - Everything worked as expected.
400 Bad Request - Usually missing a required parameter.
401 Unauthorized - No valid API key provided.
402 Request Failed - Parameters were valid but request failed.
404 Not Found - The requested item doesn’t exist.
500 Server errors - internal server error.