Developers – webPOS API – Italiano

Introduction

The ChainsidePay APIs are HTTP-based RESTful APIs that use OAuth 2.0 for authorization. API request and response bodies are formatted in JSON.

Payment Orders Overview

A payment order can be in one of the following states:

Pending
Paid
Network Dispute
Chargeback
Cancelled
Expired

When a payment order changes its state, one or more of the following callback events is sent to the merchant WebPOS:

payment.completed
payment.expired
payment.cancelled
payment.dispute.start
payment.dispute.end
payment.chargeback
payment.overpaid
payment.transaction.changed

Payment Flow

Payment Order State Machine

The transitions on the state machines are associated to the following conditions and events:

1. The payment order receives enough confirmed bitcoin transactions to cover for its required amount.

The payment.completed callback event is sent to the merchant WebPOS
If the payment order received more bitcoin than its required amount, the payment.overpaid callback event is also sent to the merchant WebPOS

2. Some of the bitcoin transactions paying the payment order lose confirmations.

The payment.dispute.start callback event is sent to the merchant WebPOS

3. The payment order regains enough confirmed bitcoin transactions to cover for its required amount.

The payment.dispute.end callback event is sent to the merchant WebPOS

4. The payment order does not regain enough confirmed bitcoin transactions to cover for its required amount before the Chargeback timeout.

The payment.chargeback callback event is sent to the merchant WebPOS
If the payment order received at least one bitcoin transaction, the payment.overpaid callback event is also sent to the merchant WebPOS

5. The buyer cancels the payment order through the Checkout Page.

The payment.cancelled callback event is sent to the merchant WebPOS
If the payment order received at least one bitcoin transaction, the payment.overpaid callback event is also sent to the merchant WebPOS

6. The payment order does not receive enough confirmed bitcoin transactions to cover for its required amount before the Expiration timeout.

The payment.expired callback event is sent to the merchant WebPOS
If the payment order received at least one bitcoin transaction, the payment.overpaid callback event is also sent to the merchant WebPOS

Payment Order States

The Chargeback, Expired, and Cancelled states are final states, meaning that a payment order will never move to another state.

Pending

A Pending payment order may have received some bitcoin transactions, but the amount of confirmed bitcoin transactions is not enough to cover for its required amount.

All new payment orders start in the Pending state.

If the payment order does not receive enough confirmed bitcoin transactions before the Expiration timeout, it will go to the Expired state.

Paid

A Paid payment order has received enough confirmed bitcoin transactions to cover for its required amount.

Network Dispute

A payment order in the Network Dispute state has reached the Paid state in the past, i.e., it received the requested number of confirmations, but later lost confirmations or some bitcoin transactions.

If the payment order in Network Dispute receives enough confirmations to be considered Paid, the dispute will be resolved and the payment order will go back to the Paid state.

If the payment order does not receive enough confirmations before the Chargeback timeout, it will go to the Chargeback state.

Chargeback

A payment order in the Chargeback state was a payment order in Network Dispute that did not receive enough confirmations to be considered Paid before the Chargeback timeout.

Cancelled

A Cancelled payment order was cancelled by the buyer through the Checkout Page.

Expired

An Expired payment order did not reach the Paid state before the Expiration timeout.

Timeouts

Expiration Timeout

A payment order can expire in two conditions:

the payment order did not receive enough bitcoin transactions to cover for the amount within 15 minutes from its creation;
the payment order did receive enough bitcoin transactions to cover for the amount within 15 minutes from its creation, but not all bitcoin transactions reached the Confirmed state within 30 days from its creation.

Chargeback Timeout

A payment order can reach the Chargeback state in two conditions:

at least one bitcoin transaction paying the payment order was reverted, and no other bitcoin transaction covered for its required amount within 24 hours;
no bitcoin transaction paying the payment order was reverted, but not all bitcoin transactions paying the payment order reached the Confirmed state within 30 days from its creation.

Payment Order Events

`payment.completed`

This callback event is sent to the merchant WebPOS when a payment order enters the Paid state for the first time.

`payment.expired`

This callback event is sent to the merchant WebPOS when a payment order expires.

`payment.cancelled`

This callback event is sent to the merchant WebPOS when a payment order is cancelled by the buyer through the Checkout Page.

`payment.dispute.start`

This callback event is sent to the merchant WebPOS when a payment order enters the Network Dispute state.

`payment.dispute.end`

This callback event is sent to the merchant WebPOS when a payment order exits the Network Dispute state and goes back to the Paid state.

`payment.chargeback`

This callback event is sent to the merchant WebPOS when a payment order exits the Network Dispute state and goes to the Chargeback state.

`payment.overpaid`

This callback event is sent to the merchant WebPOS if any of the following conditions is met:

a payment order that is already in a "final state" (Paid, Cancelled, Chargeback, Expired) receives a new transaction (a new callback is sent *for every* addictional one; that means you can receive a callback also after months the payment order has entered the final state);
a payment order enters the Paid state receiving more bitcoins than its total amount (you will receive a payment.completed callback first and then a payment.overpaid)

`payment.transaction.changed`

This callback event is sent to the merchant WebPOS when the transaction id of a bitcoin transaction paying a Paid payment order changes.

Bitcoin Transaction States

Unconfirmed

An unconfirmed bitcoin transaction has not yet received the requested number of confirmations.

Confirmed

A confirmed bitcoin transaction has received the requested number of confirmations.

Reverted

A reverted bitcoin transaction is a bitcoin transaction that appeared on the bitcoin network but was later pushed out by a competing bitcoin transaction.

Api Overview

Chainside Apis are available either in a live or sandbox environment. Environments hostnames are:

live: https://api.webpos.chainside.net
sandbox: https://api.sandbox.webpos.chainside.net

Default Headers

Request

The following headers must be included in every request:

Header	Description
X-api-version	Api version to be used (follows the one of the documentation)

Response

The following headers will be included in every response:

Header	Description
Access-Control-Allow-Origin	Origin allowed to perform the request
Access-Control-Allow-Methods	Methods allowed for the request
Access-Control-Allow-Headers	Headers allowed for the request
Access-Control-Allow-Credentials	Whether the request can be performed using credentials (Cookies/Authorization Header/TLS client certificates)
X-RateLimit-Limit	Number of allowed requests per second
X-RateLimit-Remaining	Number of remaining allowed requests per second
X-RateLimit-Reset	Remaining time (in seconds) for the rate limits to reset

Validation Rules

Validation Rule	Description
`alpha`	The value must contain only alphabetic characters
`alphadash`	The value must contain only alphabetic or dash (-) characters
`alphanum`	The value must be alphanumeric
`between`	The value must be in the given range
`betweenlen`	The value's length must be in the given range
`decimal`	The value must represent a decimal number. The value can have at most 21 digits for the integer part and 2 digits for the decimal part (i.e 999999999999999999999.99) and must be separated with a dot (.)
`equals`	The value must be equal to the given one
`equals_to`	The value must be equal to the one of the given object field
`hex`	The value must be hexadecimal
`in`	The value must be one of the given list ov values
`len`	The value's len must be of the given one
`max`	The value must not exceed the given maximum
`maxlen`	The value's length must not exceed the given maximum
`min`	The value must not be lower than the given minimum
`minlen`	The value's length must not be lower than the given minimum
`nullable`	The value can be null
`nullable_if`	The value can be null if the given condition applies
`regex`	The value must be conform to the given regex
`required`	The value is required

Pagination

Some endpoints requires pagination on responses. Paged responses will return only a subset of the total items. To query the complete set of the requested items, clients will need to set dynamically request parameters and retrieve all of the pages. Endpoints which requires pagination can be identified and contacted in the following way:

Requests

The following query parameters can be set to query paged requests

Param	Description
page	The requested page index (default: 0)
page_size	Number of items to be returned per page (default: 20, max: 40)
sort_by	The field to perform sorting on (default: 'created_at')
sort_order	Ordering for the sorting (default: 'desc')

Responses

The following parameters will be included in the paged responses

Param	Description
total_items	Total number of items
total_pages	Total number of pages given the requested page size

Tag Name	Description
Authenticated	Authentication is required to perform the request
Authenticating	Requests which provides authentication
Sandbox-Testing	Endpoints available only in sandbox mode which can be used for integration testing

Authentication

Authentication is performed using the Oauth2 protocol. A guest login must be performed prior to any unhauthenticated request.

Every authenticated request should be performed after a login request.

Authenticated request are tagged as Authenticated.

A login request should carry an Authorization: Basic header where the value is computed as: base64encode(client_id:client_secret).

Webposes client id and secret are available in the business panel selecting the created webpos.

A refresh token is not included in the responses. On session expirations, the client must perform again the login.

Confirmation, Cancellation and Callback urls

By default, the urls specified on webpos creation are used to redirect the user/send callbacks on payment order status changes. These urls can be overridden on payment order creation in the request body and are the following:

callback_url

Url contacted for every callback related to a payment-order status change.

continue_url

Url on which the user is redirected when the payment order is paid.

cancel_url

Url on which the user is redirected upon payment order cancellation.

When a payment order is created, these urls can be overrided.

As for the continue and cancel url, when chainside redirects the user on these urls, a query parameter ?payment_id is appended carrying the uuid of the payment order which can be used for retrieval.

SDKs

We have SDKs for PHP and Python. They are accessible at the following links:

SDK Java SDK PHP SDK Python

Endpoints

Authentication

Endpoints to handle authentication

Client Credentials Login

Endpoint to sign in the system

Tags: Authenticating

Request

URI

POST

/token

Header Parameters
Content-Type	`application/x-www-form-urlencoded`
Accept	`application/json`
Authorization	`Basic b64(client_id:client_secret)`

Body Parameters
grant_type	string Oauth2 Authorization's grant type Validation Rules equals: `client_credentials` required
scope	string Oauth2 scope of the client's authorization Validation Rules in: `*` required

Response

200 OK

Headers
Content-Type	`application/json`

Body Parameters
access_token	string User's access token Validation Rules required
expires_in	integer Token's expiration time Validation Rules required
id_token	string Jwt Token containing identity's informations Validation Rules regex: `^[A-Za-z0-9-_=]+\.[A-Za-z0-9-_=]+\.?[A-Za-z0-9-_.+/=]*$` required
token_type	string Token's type Validation Rules equals: `Bearer` required
scope	string Authorization's scope Validation Rules nullable

Code Example

PHP
Python
Java

                    use Chainside\SDK\WebPos\Client;
use Chainside\SDK\WebPos\Objects\ClientCredentials;

$client = new Client([
    'mode' => 'live',
    'client_id' => 'CLIENT_ID',
    'secret' => 'SECRET'
]);


$clientCredentials = new ClientCredentials([
    'grant_type' => 'client_credentials',
    'scope' => '*'
]);

$response = $client->clientCredentialsLogin()
    ->setClientCredentials($clientCredentials)
    ->run();

                

                    from webpos_sdk.actions.factory import ChainsideFactory
from webpos_sdk.objects import ClientCredentials
from webpos_sdk.api_context import ChainsideApiContext

config = {'mode': 'live',
          'client_id': '{webpos_client_id}',
          'secret': '{webpos_secret}'}

context = ChainsideApiContext(config)

login_action = ChainsideFactory(context).make('login')
login_action.client_credentiials = ClientCredentials(grant_type='client_credentials', scope='*')

response = login_action.run()
access_token = response.access_token

# Using the client object, login is executed automatically

from webpos_sdk.client import Client

c = Client(config)  # Performs the client credentials login automatically

                

                    import net.webpossdk.api.ChainsideClient;

HashMap config = new HashMap<>();
config.put("mode", "sandbox");
config.put("clientId", "{webpos_client_id}");
config.put("secret", "{webpos_secret}");

// Client instantiation automatically performs the login and stores the access token in cache
ChainsideClient client = new ChainsideClient(config);

Payments

Endpoint to handle payment orders

Delete Payment Order

Endpoint to cancel a payment order

Tags: Authenticated

Request

URI

DELETE

/payment-order/{payment_order_uuid}

Header Parameters
Content-Type	`application/json`
Accept	`application/json`

URI params
payment_order_uuid	uuid Validation Rules required

Response

200 OK

Headers
Content-Type	`application/json`

Body Parameters
cancel_url	url The URL where the user is redirected upon payment order expiration/cancellation Validation Rules regex[https_url]: `^https://` required

Possible Errors

3001 Not Found

Code Example

PHP
Python
Java

                    use Chainside\SDK\WebPos\Client;

$context = new Client([
    'mode' => 'live',
    'client_id' => 'CLIENT_ID',
    'secret' => 'SECRET'
]);

$response = $client->deletePaymentOrder()
    ->setPaymentOrderUuid('3bf64dd9-72b0-46e1-9282-6a571bf1f05c')
    ->run();

                

                    from webpos_sdk.client import Client

config = {'mode': 'live',
          'client_id': '{webpos_client_id}',
          'secret': '{webpos_secret}'}

client = Client(config)
client.delete_payment_order(payment_order_uuid='{uuid of the payment order to be cancelled}')

                

                    import net.webpossdk.api.ChainsideClient;

HashMap config = new HashMap<>();
config.put("mode", "sandbox");
config.put("clientId", "{webpos_client_id}");
config.put("secret", "{webpos_secret}");

ChainsideClient client = new ChainsideClient(config);

client.deletePaymentOrder("{payment_order_uuid}");
                

Get Payment Order

Endpoint to retrieve a payment order

Tags: Authenticated

Request

URI

GET

/payment-order/{payment_order_uuid}

Header Parameters
Content-Type	`application/json`
Accept	`application/json`

URI params
payment_order_uuid	uuid Validation Rules required

Response

200 OK

Headers
Content-Type	`application/json`

Body Parameters
address	base58 Bitcoin address of the payment order Validation Rules required
amount	string Fiat's amount of the payment order Validation Rules decimal required
btc_amount	integer Bitcoin amount of the payment order Validation Rules required
callback_url	url The URL contacted to send callbacks related to payment status changes Validation Rules regex[https_url]: `^https://`
created_at	ISO_8601_date Creation date of the payment order Validation Rules required
created_by	PaymentOrderCreator Data of the pos which created the payment order Validation Rules required
currency	CurrencyRetrieval Fiat currency of the payment order Validation Rules required
details	string Payment order's details Validation Rules nullable
expiration_time	ISO_8601_date Expiration date of the payment order Validation Rules required
expires_in	integer Expiration time of the payment order Validation Rules required
rate	RateRetrieval Crypto/Fiat rate of the payment order Validation Rules required
redirect_url	url URL where to redirect the user to perform the payment Validation Rules regex[https_url]: `^https://`
reference	string Business' reference for the payment order Validation Rules nullable required
required_confirmations	integer Required confirmations for transactions paying the payment order Validation Rules required
resolved_at	ISO_8601_date Time at which either the payment order has been fully paid or is expired Validation Rules required nullable
dispute_start_date	ISO_8601_date Time at which either the payment order has been fully paid or is expired Validation Rules required nullable
chargeback_date	ISO_8601_date Time at which either the payment order has been fully paid or is expired Validation Rules required nullable
state	PaymentOrderState Current payment state of the payment order Validation Rules required
transactions	array[Transaction] Transactions paying the payment order Validation Rules nullable required
uri	string Bitcoin uri Validation Rules required
uuid	uuid UUID of the payment order Validation Rules required

Possible Errors

3001 Not Found

Code Example

PHP
Python
Java

                    use Chainside\SDK\WebPos\Client;

$client = new Client([
    'mode' => 'live',
    'client_id' => 'CLIENT_ID',
    'secret' => 'SECRET'
]);

$response = $client->getPaymentOrder()
    ->setPaymentOrderUuid('3bf64dd9-72b0-46e1-9282-6a571bf1f05c')
    ->run();

                

                    from webpos_sdk.client import Client

config = {'mode': 'live',
          'client_id': '{webpos_client_id}',
          'secret': '{webpos_secret}'}

client = Client(config)
payment_order = client.get_payment_order(payment_order_uuid='{uuid of the payment order to be cancelled}')
payment_address = payment_order.address

                

                    import net.webpossdk.api.ChainsideClient;
import net.webpossdk.object.PaymentOrderRetrieval;

HashMap config = new HashMap<>();
config.put("mode", "sandbox");
config.put("clientId", "{webpos_client_id}");
config.put("secret", "{webpos_secret}");

ChainsideClient client = new ChainsideClient(config);
PaymentOrderRetrieval payment = client.getPaymentOrder("{payment_order_uuid}");
                

Get Payment Orders

Endpoint to retrieve all business' payment orders

Tags: Authenticated

Request

URI

GET

/payment-order

Header Parameters
Content-Type	`application/json`
Accept	`application/json`

Query Parameters
status	string Status of the payment orders to retrieve Validation Rules in: `pending,partial,mempool_unconfirmed,unconfirmed,paid,cancelled,expired,network_dispute,mempool_network_dispute,possible_chargeback,chargeback`
sort_by	string Field used to sort pages (default: created_at) Validation Rules in: `amount,created_at` nullable
sort_order	string Ordering to be used for the sort (default: desc) Validation Rules in: `asc,desc` nullable
page	integer Index of the page to be returned (default: 0) Validation Rules nullable min: `0`
page_size	integer Size of the returned page (default: 20) Validation Rules nullable max: `40`

Response

200 OK

Headers
Content-Type	`application/json`

Body Parameters
paymentorders	array[PaymentOrderRetrieval] Business' payment orders Validation Rules required nullable
total_pages	integer Total number of pages given the requested page size Validation Rules required
total_items	integer Total number of items Validation Rules required

Possible Errors

1012 Forbidden

Create Payment Order

Endpoint to create a new payment order

Tags: Authenticated

Request

URI

POST

/payment-order

Header Parameters
Content-Type	`application/json`
Accept	`application/json`

Body Parameters
amount	string Payment order's fiat amount Validation Rules required decimal
cancel_url	url The URL where the user is redirected upon successful payment order expiration/cancellation Validation Rules regex[https_url]: `^https://` nullable maxlen: `300`
continue_url	url The URL where the user is redirected upon successful payment Validation Rules regex[https_url]: `^https://` nullable maxlen: `300`
callback_url	url The URL contacted to send callbacks related to payment status changes Validation Rules regex[https_url]: `^https://` nullable maxlen: `300`
details	string Payment order's details Validation Rules maxlen: `300` nullable
reference	string Business' reference of the payment order Validation Rules maxlen: `300` nullable
required_confirmations	integer Required confirmations for transactions paying the payment order Validation Rules min: `0` nullable

Response

201 Created

Headers
Content-Type	`application/json`

Body Parameters
address	string Bitcoin address of the payment order Validation Rules regex: `^` required
amount	integer Crypto amount of the payment order Validation Rules required
expiration_time	ISO_8601_date Expiration's date of the payment order Validation Rules required
expires_in	integer Expiration's time of the payment order Validation Rules required
rate	RateRetrieval Crypto/Fiat rate of the payment order Validation Rules required
redirect_url	url URL where to redirect the user to perform the payment Validation Rules regex[https_url]: `^https://` required nullable
uri	string Bitcoin uri according to BIP 21 (https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki) Validation Rules regex: `^` required
uuid	uuid UUID of the payment order Validation Rules required
created_at	ISO_8601_date Creation date of the payment order Validation Rules nullable
reference	string Payment Order reference Validation Rules nullable

Possible Errors

0001 Validation Error
4006 Functionality Down

Code Example

PHP
Python
Java

                    use Chainside\SDK\WebPos\Client;
use Chainside\SDK\WebPos\Objects\PaymentOrderCreation;

$client = new Client([
    'mode' => 'live',
    'client_id' => 'CLIENT_ID',
    'secret' => 'SECRET'
]);

$paymentOrder = new PaymentOrderCreation([
    'amount' => '10.00',
    'cancel_url' => 'https://example.com/cancel',
    'continue_url' => 'https://example.com/continue',
    'details' => 'details',
    'reference' => 'reference',
    'required_confirmations' => 6
]);

$response = $client->createPaymentOrder()
    ->setPaymentOrderCreation($paymentOrder)
    ->run();


                

                    from webpos_sdk.objects import PaymentOrder
from webpos_sdk.client import Client

config = {'mode': 'live',
          'client_id': '{webpos_client_id}',
          'secret': '{webpos_secret}'}

client = Client(config)
payment_order = PaymentOrder(amount='10.00',
                             cancel_url='https://cancel.com',
                             continue_url='https://continue.com',
                             details='details',
                             reference='reference',
                             required_confirmations=6)

response = client.create_payment_order(payment_order)
btc_address = response.address

                

                    import net.webpossdk.api.ChainsideClient;
import net.webpossdk.object.CallbackList;

HashMap config = new HashMap<>();
config.put("mode", "sandbox");
config.put("clientId", "{webpos_client_id}");
config.put("secret", "{webpos_secret}");

PaymentOrderCreation paymentOrder = new PaymentOrderCreation();
paymentOrder.setAmount("10.00");
paymentOrder.setReference("#1");
paymentOrder.setDetails("#1 details");
paymentOrder.setRequiredConfirmations(3);
PaymentOrderCreationResponse resp = client.createPaymentOrder(paymentOrder);

String btcAddress = resp.address // will output the payment order address

                

Callbacks

Every Callback Request expects a 2xx response from the webpos callback url. For every different response status code, the callback will be sent again with a delay until a success response is received or ~48h passed from the first sent request

Structure

Callback Request

Header Parameters
Content-Type	`application/json`
Chainside-Signature	`<signature>`

Body Parameters
event	string Event which triggered the callback Validation Rules required equals: `payment.cancelled`
created_at	ISO_8601_date Date in which the callback was sent Validation Rules required
object_type	string Type of the object sent in the callback Validation Rules required nullable
object	object

Verification

Payments' callbacks carry a chainside-signature header. This signature is computed using HMAC-SHA512 where the signed data is the raw request body and the key is computed as SHA256({webpos_secret})

Callback Events

PaymentCancelled

event	`payment.cancelled`
object	CallbackPaymentOrder

PaymentOverpaid

event	`payment.overpaid`
object	CallbackPaymentOrder

PaymentExpired

event	`payment.expired`
object	CallbackPaymentOrder

PaymentDisputeStart

event	`payment.dispute.start`
object	CallbackPaymentOrder

PaymentChargeback

event	`payment.chargeback`
object	CallbackPaymentOrder

PaymentCompleted

event	`payment.completed`
object	CallbackPaymentOrder

PaymentDisputeEnd

event	`payment.dispute.end`
object	CallbackPaymentOrder

Testing

Flow

The api server exposes endpoints in the sandbox mode to test the integration with the chainside backend via api requests. In testing environments, fake bitcoin transactions are generated and callback requests are sent due to payments status changes. To perform a test, the following steps must be performed:

- Create a webpos on the sandbox api (via business panel)

- Create a payment order on the sandbox api using the credentials of the sandbox webpos

- Contact testing endpoints to update the payment state triggering the sending of callback requests from the chainside api server to the provided callback url

Endpoints for sandbox testing are tagged with the "Sandbox-Testing" tags. Here is an overview:

- Get Payments Callbacks Retrieves the available callbacks accordingly to the current payment state

- Payment Order status update Updates the payment state and triggers the callback request

- Reset Test Payment Resets the payment order to the starting state

When a payment update is triggered, transactions are generated to update the paid amount on the payment order accordingly to the triggered event. The payment-order can then be retrieved and generated transactions are returned.

When a payment reset occurs, every generated transaction is deleted

Payment orders created in sandbox mode does not expire within the usual expiration time window; the callback 'payment.expired' can be triggered during the testing, updating the payment order state

Sandbox payment orders are deleted automatically after 30 days since the creation

Endpoints

Endpoints for testing payment orders callbacks

Get Payment Callbacks

Endpoint to retrieve the possible sent callbacks based on legal payment's state transitions

Tags: Authenticated Sandbox-Testing

Request

URI

GET

/payment-order/{payment_order_uuid}/callbacks

Header Parameters
Content-Type	`application/json`
Accept	`application/json`

URI params
payment_order_uuid	uuid Validation Rules required

Response

200 OK

Headers
Content-Type	`application/json`

Body Parameters
callbacks	array[Callback] Valid payment transitions callbacks Validation Rules required

Possible Errors

0001 Validation Error
3001 Not Found

Code Example

Python
Java

                    from webpos_sdk.client import Client

config = {'mode': 'live',
          'client_id': '{webpos_client_id}',
          'secret': '{webpos_secret}'}

client = Client(config)
# returns the list of available callbacks given the payment order state
callback_list = client.get_callbacks('{payment_order_uuid}')

                

                    import net.webpossdk.api.ChainsideClient;
import net.webpossdk.object.CallbackList;

HashMap config = new HashMap<>();
config.put("mode", "sandbox");
config.put("clientId", "{webpos_client_id}");
config.put("secret", "{webpos_secret}");

ChainsideClient client = new ChainsideClient(config);
// will return the list of available callbacks given the payment order state
CallbackList validCallbacks = client.getCallbacks("{payment_order_uuid}");
                

Reset Test Payment

Endpoint to reset a payment order to its initial state

Tags: Authenticated Sandbox-Testing

Request

URI

PATCH

/payment-order/{payment_order_uuid}/test/reset

Header Parameters
Content-Type	`application/json`
Accept	`application/json`

URI params
payment_order_uuid	uuid Validation Rules required

Response

200 OK

Headers
Content-Type	`application/json`

Body Parameters
address	base58 Bitcoin address of the payment order Validation Rules required
amount	string Fiat's amount of the payment order Validation Rules decimal required
btc_amount	integer Bitcoin amount of the payment order Validation Rules required
callback_url	url The URL contacted to send callbacks related to payment status changes Validation Rules regex[https_url]: `^https://` required
created_at	ISO_8601_date Creation date of the payment order Validation Rules required
created_by	PaymentOrderCreator Data of the pos which created the payment order Validation Rules required
currency	CurrencyRetrieval Fiat currency of the payment order Validation Rules required
details	string Payment order's details Validation Rules required nullable
expiration_time	ISO_8601_date Expiration date of the payment order Validation Rules required
expires_in	integer Expiration time of the payment order Validation Rules required
rate	RateRetrieval Crypto/Fiat rate of the payment order Validation Rules required
redirect_url	url URL where to redirect the user to perform the payment Validation Rules regex[https_url]: `^https://` required
reference	string Business' reference for the payment order Validation Rules nullable required
required_confirmations	integer Required confirmations for transactions paying the payment order Validation Rules required
resolved_at	ISO_8601_date Time at which either the payment order has been fully paid or is expired Validation Rules required nullable
dispute_start_date	ISO_8601_date Time at which either the payment order has been fully paid or is expired Validation Rules required nullable
chargeback_date	ISO_8601_date Time at which either the payment order has been fully paid or is expired Validation Rules required nullable
state	PaymentOrderState Current payment state of the payment order Validation Rules required
transactions	array[Transaction] Transactions paying the payment order Validation Rules nullable required
uri	string Bitcoin uri Validation Rules required
uuid	uuid UUID of the payment order Validation Rules required

Possible Errors

3001 Not Found

Code Example

Python
Java

                    from webpos_sdk.client import Client

config = {'mode': 'live',
          'client_id': '{webpos_client_id}',
          'secret': '{webpos_secret}'}

client = Client(config)
# resets the test payment to its initial state
callback_list = client.payment_reset('{payment_order_uuid}')

                

                    import net.webpossdk.api.ChainsideClient;

HashMap config = new HashMap<>();
config.put("mode", "sandbox");
config.put("clientId", "{webpos_client_id}");
config.put("secret", "{webpos_secret}");

ChainsideClient client = new ChainsideClient(config);

client.paymentReset("{payment_order_uuid}"); // will restore the payment order to its initial state

Payment order status update

Endpoint to change a payment order status and trigger callbacks

Tags: Authenticated Sandbox-Testing

Request

URI

PATCH

/payment-order/{payment_order_uuid}/test/

Header Parameters
Content-Type	`application/json`
Accept	`application/json`

URI params
payment_order_uuid	uuid Validation Rules required

Body Parameters
callback	string Name of the callback to be sent Validation Rules required

Response

200 OK

Headers
Content-Type	`application/json`

Possible Errors

0013 Invalid Callback
3001 Not Found

Code Example

Python
Java

                    from webpos_sdk.client import Client
from webpos_sdk.objects import PaymentUpdateObject

config = {'mode': 'live',
          'client_id': '{webpos_client_id}',
          'secret': '{webpos_secret}'}

client = Client(config)
# will trigger the callback relative to the payment.completed event

payment_update_body = PaymentUpdateObject("payment.completed")
client.payment_update("{payment_order_uuid}", payment_update_body)

                

                    import net.webpossdk.api.ChainsideClient;
import net.webpossdk.objects.PaymentUpdateObject;

HashMap config = new HashMap<>();
config.put("mode", "sandbox");
config.put("clientId", "{webpos_client_id}");
config.put("secret", "{webpos_secret}");

ChainsideClient client = new ChainsideClient(config);

PaymentUpdateObject paymentUpdateObject = new PaymentUpdateObject();
paymentUpdateObject.setCallback("payment.completed")

client.paymentUpdate("{payment_order_uuid}", paymentUpdateObject); // will trigger the sending of a "payment.completed" callback

Types

Primitive Types

Primitive Types List

string
boolean
integer

Custom Types

ISO_8601_date

Date field

Base Type	string
regex
Example	`2018-01-12 11:23:43`

uuid

Represents a Universally Unique IDentifier v4 (RFC4122), it is a 128-bit number represented as a string of 32 hexadecimal digits, displayed in five groups separated by hyphens, in the form 8-4-4-4-12

Base Type	string
regex
Example	`123e4567-e89b-12d3-a456-426655440000`

email

Email field

Base Type	string
regex
Example	`user@domain.com`

base64

Base 64 encoded string

Base Type	string
regex
Example	`None`

base58

Base 58 encoded string

Base Type	string
regex
Example	`None`

url

Url field

Base Type	string
regex
Example	`https://www.domain.com`

Objects

ClientCredentials

Data required to perform a confidential client login

PROPERTIES
grant_type	string Oauth2 Authorization's grant type Validation Rules equals :`client_credentials` required
scope	string Oauth2 scope of the client's authorization Validation Rules in :`*` required

JSON Representation


{"_name": "client_credentials", "_schema": {"grant_type": {"description": "Oauth2 Authorization\u0027s grant type", "rules": ["equals:client_credentials", "required"], "type": "string"}, "scope": {"description": "Oauth2 scope of the client\u0027s authorization", "rules": ["in:*", "required"], "type": "string"}}, "description": "Data required to perform a confidential client login", "expanded_schema": {"rules": [], "schema": {"grant_type": {"description": "Oauth2 Authorization\u0027s grant type", "rules": ["equals:client_credentials", "required"], "type": "string"}, "scope": {"description": "Oauth2 scope of the client\u0027s authorization", "rules": ["in:*", "required"], "type": "string"}}, "type": "object"}, "rules": []}

ClientCredentialsLoginResponse

Response data for a login performed by a confidential client.

PROPERTIES
access_token	string User's access token Validation Rules required
expires_in	integer Token's expiration time Validation Rules required
id_token	string Jwt Token containing identity's informations Validation Rules regex :`^[A-Za-z0-9-_=]+\.[A-Za-z0-9-_=]+\.?[A-Za-z0-9-_.+/=]*$` required
token_type	string Token's type Validation Rules equals :`Bearer` required
scope	string Authorization's scope Validation Rules nullable

JSON Representation


{"_name": "client_credentials_login_response", "_schema": {"access_token": {"description": "User\u0027s access token", "rules": ["required"], "type": "string"}, "expires_in": {"description": "Token\u0027s expiration time", "rules": ["required"], "type": "integer"}, "id_token": {"description": "Jwt Token containing identity\u0027s informations", "rules": ["regex:^[A-Za-z0-9-_=]+\\.[A-Za-z0-9-_=]+\\.?[A-Za-z0-9-_.+/=]*$", "required"], "type": "string"}, "scope": {"description": "Authorization\u0027s scope", "rules": ["nullable"], "type": "string"}, "token_type": {"description": "Token\u0027s type", "rules": ["equals:Bearer", "required"], "type": "string"}}, "description": "Response data for a login performed by a confidential client.", "expanded_schema": {"rules": [], "schema": {"access_token": {"description": "User\u0027s access token", "rules": ["required"], "type": "string"}, "expires_in": {"description": "Token\u0027s expiration time", "rules": ["required"], "type": "integer"}, "id_token": {"description": "Jwt Token containing identity\u0027s informations", "rules": ["regex:^[A-Za-z0-9-_=]+\\.[A-Za-z0-9-_=]+\\.?[A-Za-z0-9-_.+/=]*$", "required"], "type": "string"}, "scope": {"description": "Authorization\u0027s scope", "rules": ["nullable"], "type": "string"}, "token_type": {"description": "Token\u0027s type", "rules": ["equals:Bearer", "required"], "type": "string"}}, "type": "object"}, "rules": []}

PaymentOrderDeletionResponse

Payment order deletion response

PROPERTIES
cancel_url	url The URL where the user is redirected upon payment order expiration/cancellation Validation Rules regex :`https_url` required

JSON Representation


{"_name": "payment_order_deletion_response", "_schema": {"cancel_url": {"description": "The URL where the user is redirected upon payment order expiration/cancellation", "rules": ["regex[https_url]:^https://", "required"], "type": "url"}}, "description": "Payment order deletion response", "expanded_schema": {"rules": [], "schema": {"cancel_url": {"description": "The URL where the user is redirected upon payment order expiration/cancellation", "rules": ["regex[https_url]:^https://", "required"], "type": "url"}}, "type": "object"}, "rules": []}

PaymentOrderRetrieval

Payment order retrieval data

PROPERTIES
address	base58 Bitcoin address of the payment order Validation Rules required
amount	string Fiat's amount of the payment order Validation Rules decimal required
btc_amount	integer Bitcoin amount of the payment order Validation Rules required
callback_url	url The URL contacted to send callbacks related to payment status changes Validation Rules regex :`https_url`
created_at	ISO_8601_date Creation date of the payment order Validation Rules required
created_by	PaymentOrderCreator Data of the pos which created the payment order Validation Rules required
currency	CurrencyRetrieval Fiat currency of the payment order Validation Rules required
details	string Payment order's details Validation Rules nullable
expiration_time	ISO_8601_date Expiration date of the payment order Validation Rules required
expires_in	integer Expiration time of the payment order Validation Rules required
rate	RateRetrieval Crypto/Fiat rate of the payment order Validation Rules required
redirect_url	url URL where to redirect the user to perform the payment Validation Rules regex :`https_url`
reference	string Business' reference for the payment order Validation Rules nullable required
required_confirmations	integer Required confirmations for transactions paying the payment order Validation Rules required
resolved_at	ISO_8601_date Time at which either the payment order has been fully paid or is expired Validation Rules required nullable
dispute_start_date	ISO_8601_date Time at which either the payment order has been fully paid or is expired Validation Rules required nullable
chargeback_date	ISO_8601_date Time at which either the payment order has been fully paid or is expired Validation Rules required nullable
state	PaymentOrderState Current payment state of the payment order Validation Rules required
transactions	array[Transaction] Transactions paying the payment order Validation Rules nullable required
uri	string Bitcoin uri Validation Rules required
uuid	uuid UUID of the payment order Validation Rules required

JSON Representation


{"_name": "payment_order_retrieval", "_schema": {"address": {"description": "Bitcoin address of the payment order", "rules": ["required"], "type": "base58"}, "amount": {"description": "Fiat\u0027s amount of the payment order", "rules": ["decimal", "required"], "type": "string"}, "btc_amount": {"description": " Bitcoin amount of the payment order", "rules": ["required"], "type": "integer"}, "callback_url": {"description": "The URL contacted to send callbacks related to payment status changes", "rules": ["regex[https_url]:^https://"], "type": "url"}, "chargeback_date": {"description": "Time at which either the payment order has been fully paid or is expired", "rules": ["required", "nullable"], "type": "ISO_8601_date"}, "created_at": {"description": "Creation date of the payment order", "rules": ["required"], "type": "ISO_8601_date"}, "created_by": {"description": "Data of the pos which created the payment order", "rules": ["required"], "type": "object(payment_order_creator)"}, "currency": {"description": "Fiat currency of the payment order", "rules": ["required"], "type": "object(currency_retrieval)"}, "details": {"description": "Payment order\u0027s details", "rules": ["nullable"], "type": "string"}, "dispute_start_date": {"description": "Time at which either the payment order has been fully paid or is expired", "rules": ["required", "nullable"], "type": "ISO_8601_date"}, "expiration_time": {"description": "Expiration date of the payment order", "rules": ["required"], "type": "ISO_8601_date"}, "expires_in": {"description": " Expiration time of the payment order", "rules": ["required"], "type": "integer"}, "rate": {"description": "Crypto/Fiat rate of the payment order", "rules": ["required"], "type": "object(rate_retrieval)"}, "redirect_url": {"description": "URL where to redirect the user to perform the payment", "rules": ["regex[https_url]:^https://"], "type": "url"}, "reference": {"description": "Business\u0027 reference for the payment order", "rules": ["nullable", "required"], "type": "string"}, "required_confirmations": {"description": "Required confirmations for transactions paying the payment order", "rules": ["required"], "type": "integer"}, "resolved_at": {"description": "Time at which either the payment order has been fully paid or is expired", "rules": ["required", "nullable"], "type": "ISO_8601_date"}, "state": {"description": "Current payment state of the payment order", "rules": ["required"], "type": "object(payment_order_state)"}, "transactions": {"description": "Transactions paying the payment order", "rules": ["nullable", "required"], "type": "array[transaction]"}, "uri": {"description": "Bitcoin uri", "rules": ["required"], "type": "string"}, "uuid": {"description": "UUID of the payment order", "rules": ["required"], "type": "uuid"}}, "description": "Payment order retrieval data", "expanded_schema": {"rules": [], "schema": {"address": {"description": "Bitcoin address of the payment order", "rules": ["required"], "type": "base58"}, "amount": {"description": "Fiat\u0027s amount of the payment order", "rules": ["decimal", "required"], "type": "string"}, "btc_amount": {"description": " Bitcoin amount of the payment order", "rules": ["required"], "type": "integer"}, "callback_url": {"description": "The URL contacted to send callbacks related to payment status changes", "rules": ["regex[https_url]:^https://"], "type": "url"}, "chargeback_date": {"description": "Time at which either the payment order has been fully paid or is expired", "rules": ["required", "nullable"], "type": "ISO_8601_date"}, "created_at": {"description": "Creation date of the payment order", "rules": ["required"], "type": "ISO_8601_date"}, "created_by": {"rules": ["required"], "schema": {"active": {"description": "Wheter the creator active", "rules": [], "type": "boolean"}, "deposit_account": {"rules": ["required"], "schema": {"name": {"description": "Deposit account\u0027s name", "rules": ["required"], "type": "string"}, "type": {"description": "Deposit account\u0027s type", "rules": ["in:bank,bitcoin", "required"], "type": "string"}, "uuid": {"description": "Deposit account\u0027s uuid", "rules": ["required"], "type": "uuid"}}, "type": "object"}, "name": {"description": "Payment order creator\u0027s name", "rules": ["required"], "type": "string"}, "type": {"description": "Payment order creator\u0027s type", "rules": ["required", "in:web,mobile"], "type": "string"}, "uuid": {"description": "Payment order creator\u0027s uuid", "rules": ["required"], "type": "uuid"}}, "type": "object"}, "currency": {"rules": ["required"], "schema": {"name": {"description": "Name of the currency", "rules": ["required"], "type": "string"}, "type": {"description": "Currency\u0027s type (fiat/crypto)", "rules": ["in:crypto,fiat", "required"], "type": "string"}, "uuid": {"description": "UUID of the currency", "rules": ["required"], "type": "uuid"}}, "type": "object"}, "details": {"description": "Payment order\u0027s details", "rules": ["nullable"], "type": "string"}, "dispute_start_date": {"description": "Time at which either the payment order has been fully paid or is expired", "rules": ["required", "nullable"], "type": "ISO_8601_date"}, "expiration_time": {"description": "Expiration date of the payment order", "rules": ["required"], "type": "ISO_8601_date"}, "expires_in": {"description": " Expiration time of the payment order", "rules": ["required"], "type": "integer"}, "rate": {"rules": ["required"], "schema": {"created_at": {"description": "Creation\u0027s date of the rate", "rules": ["required"], "type": "ISO_8601_date"}, "from": {"description": "Starting currency for rate calculation", "rules": [], "type": "string"}, "source": {"description": "Exchange providing the rate", "rules": ["required"], "type": "string"}, "to": {"description": "Target currency for rate calculation", "rules": [], "type": "string"}, "value": {"description": "Value of the rate", "rules": ["decimal", "required"], "type": "string"}}, "type": "object"}, "redirect_url": {"description": "URL where to redirect the user to perform the payment", "rules": ["regex[https_url]:^https://"], "type": "url"}, "reference": {"description": "Business\u0027 reference for the payment order", "rules": ["nullable", "required"], "type": "string"}, "required_confirmations": {"description": "Required confirmations for transactions paying the payment order", "rules": ["required"], "type": "integer"}, "resolved_at": {"description": "Time at which either the payment order has been fully paid or is expired", "rules": ["required", "nullable"], "type": "ISO_8601_date"}, "state": {"rules": ["required"], "schema": {"blockchain_status": {"description": "Payment order\u0027s internal status", "rules": ["in:pending,partial,mempool_unconfirmed,unconfirmed,paid,cancelled,expired,network_dispute,mempool_network_dispute,possible_chargeback,chargeback", "required"], "type": "string"}, "in_confirmation": {"rules": ["nullable", "required"], "schema": {"crypto": {"description": "Cryto Amount", "rules": ["required"], "type": "integer"}, "fiat": {"description": "Fiat Amount", "rules": ["required", "decimal"], "type": "string"}}, "type": "object"}, "paid": {"rules": ["nullable", "required"], "schema": {"crypto": {"description": "Cryto Amount", "rules": ["required"], "type": "integer"}, "fiat": {"description": "Fiat Amount", "rules": ["required", "decimal"], "type": "string"}}, "type": "object"}, "status": {"description": "Payment order\u0027s status", "rules": ["in:pending,paid,cancelled,expired,network_dispute,chargeback", "required"], "type": "string"}, "unpaid": {"rules": ["nullable", "required"], "schema": {"crypto": {"description": "Cryto Amount", "rules": ["required"], "type": "integer"}, "fiat": {"description": "Fiat Amount", "rules": ["required", "decimal"], "type": "string"}}, "type": "object"}}, "type": "object"}, "transactions": {"elements": {"rules": [], "schema": {"blockchain_status": {"description": "Transaction\u0027s internal status", "rules": ["required", "in:mempool,unconfirmed,confirmed,reverted"], "type": "string"}, "created_at": {"description": "", "rules": ["required"], "type": "ISO_8601_date"}, "normalized_txid": {"description": "Transaction\u0027s normalized id (DEPRECATED)", "rules": ["len:64", "required"], "type": "string"}, "outs": {"elements": {"rules": [], "schema": {"amount": {"description": "Output\u0027s amount", "rules": ["required"], "type": "integer"}, "n": {"description": "Transaction output\u0027s index", "rules": ["required"], "type": "integer"}}, "type": "object"}, "rules": ["required"], "type": "array"}, "outs_sum": {"description": "Paying amount of the transaction", "rules": ["required"], "type": "integer"}, "status": {"description": "Transaction\u0027s status", "rules": ["required", "in:unconfirmed,confirmed,reverted"], "type": "string"}, "txid": {"description": "Transaction\u0027s id", "rules": ["len:64", "required"], "type": "string"}}, "type": "object"}, "rules": ["nullable", "required"], "type": "array"}, "uri": {"description": "Bitcoin uri", "rules": ["required"], "type": "string"}, "uuid": {"description": "UUID of the payment order", "rules": ["required"], "type": "uuid"}}, "type": "object"}, "rules": []}

PaymentOrderCreator

Data of payment order's creator

PROPERTIES
deposit_account	DepositAccountLite Deposit account associated to the payment order's creator Validation Rules required
name	string Payment order creator's name Validation Rules required
type	string Payment order creator's type Validation Rules required in :`web,mobile`
uuid	uuid Payment order creator's uuid Validation Rules required
active	boolean Wheter the creator active

JSON Representation


{"_name": "payment_order_creator", "_schema": {"active": {"description": "Wheter the creator active", "rules": [], "type": "boolean"}, "deposit_account": {"description": "Deposit account associated to the payment order\u0027s creator", "rules": ["required"], "type": "object(deposit_account_lite)"}, "name": {"description": "Payment order creator\u0027s name", "rules": ["required"], "type": "string"}, "type": {"description": "Payment order creator\u0027s type", "rules": ["required", "in:web,mobile"], "type": "string"}, "uuid": {"description": "Payment order creator\u0027s uuid", "rules": ["required"], "type": "uuid"}}, "description": "Data of payment order\u0027s creator", "expanded_schema": {"rules": [], "schema": {"active": {"description": "Wheter the creator active", "rules": [], "type": "boolean"}, "deposit_account": {"rules": ["required"], "schema": {"name": {"description": "Deposit account\u0027s name", "rules": ["required"], "type": "string"}, "type": {"description": "Deposit account\u0027s type", "rules": ["in:bank,bitcoin", "required"], "type": "string"}, "uuid": {"description": "Deposit account\u0027s uuid", "rules": ["required"], "type": "uuid"}}, "type": "object"}, "name": {"description": "Payment order creator\u0027s name", "rules": ["required"], "type": "string"}, "type": {"description": "Payment order creator\u0027s type", "rules": ["required", "in:web,mobile"], "type": "string"}, "uuid": {"description": "Payment order creator\u0027s uuid", "rules": ["required"], "type": "uuid"}}, "type": "object"}, "rules": []}

DepositAccountLite

Deposit account lite object when sent nested in other api objects

PROPERTIES
name	string Deposit account's name Validation Rules required
type	string Deposit account's type Validation Rules in :`bank,bitcoin` required
uuid	uuid Deposit account's uuid Validation Rules required

JSON Representation


{"_name": "deposit_account_lite", "_schema": {"name": {"description": "Deposit account\u0027s name", "rules": ["required"], "type": "string"}, "type": {"description": "Deposit account\u0027s type", "rules": ["in:bank,bitcoin", "required"], "type": "string"}, "uuid": {"description": "Deposit account\u0027s uuid", "rules": ["required"], "type": "uuid"}}, "description": "Deposit account lite object when sent nested in other api objects", "expanded_schema": {"rules": [], "schema": {"name": {"description": "Deposit account\u0027s name", "rules": ["required"], "type": "string"}, "type": {"description": "Deposit account\u0027s type", "rules": ["in:bank,bitcoin", "required"], "type": "string"}, "uuid": {"description": "Deposit account\u0027s uuid", "rules": ["required"], "type": "uuid"}}, "type": "object"}, "rules": []}

CurrencyRetrieval

Currency Data

PROPERTIES
name	string Name of the currency Validation Rules required
type	string Currency's type (fiat/crypto) Validation Rules in :`crypto,fiat` required
uuid	uuid UUID of the currency Validation Rules required

JSON Representation


{"_name": "currency_retrieval", "_schema": {"name": {"description": "Name of the currency", "rules": ["required"], "type": "string"}, "type": {"description": "Currency\u0027s type (fiat/crypto)", "rules": ["in:crypto,fiat", "required"], "type": "string"}, "uuid": {"description": "UUID of the currency", "rules": ["required"], "type": "uuid"}}, "description": "Currency Data", "expanded_schema": {"rules": [], "schema": {"name": {"description": "Name of the currency", "rules": ["required"], "type": "string"}, "type": {"description": "Currency\u0027s type (fiat/crypto)", "rules": ["in:crypto,fiat", "required"], "type": "string"}, "uuid": {"description": "UUID of the currency", "rules": ["required"], "type": "uuid"}}, "type": "object"}, "rules": []}

RateRetrieval

Rate Data

PROPERTIES
created_at	ISO_8601_date Creation's date of the rate Validation Rules required
source	string Exchange providing the rate Validation Rules required
value	string Value of the rate Validation Rules decimal required
from	string Starting currency for rate calculation
to	string Target currency for rate calculation

JSON Representation


{"_name": "rate_retrieval", "_schema": {"created_at": {"description": "Creation\u0027s date of the rate", "rules": ["required"], "type": "ISO_8601_date"}, "from": {"description": "Starting currency for rate calculation", "rules": [], "type": "string"}, "source": {"description": "Exchange providing the rate", "rules": ["required"], "type": "string"}, "to": {"description": "Target currency for rate calculation", "rules": [], "type": "string"}, "value": {"description": "Value of the rate", "rules": ["decimal", "required"], "type": "string"}}, "description": "Rate Data", "expanded_schema": {"rules": [], "schema": {"created_at": {"description": "Creation\u0027s date of the rate", "rules": ["required"], "type": "ISO_8601_date"}, "from": {"description": "Starting currency for rate calculation", "rules": [], "type": "string"}, "source": {"description": "Exchange providing the rate", "rules": ["required"], "type": "string"}, "to": {"description": "Target currency for rate calculation", "rules": [], "type": "string"}, "value": {"description": "Value of the rate", "rules": ["decimal", "required"], "type": "string"}}, "type": "object"}, "rules": []}

PaymentOrderState

Data describing the current state of a payment order

PROPERTIES
in_confirmation	PaidStatus Payment order's paid but unconfirmed amount Validation Rules required nullable
paid	PaidStatus Payment order's paid amount Validation Rules required nullable
status	string Payment order's status Validation Rules in :`pending,paid,cancelled,expired,network_dispute,chargeback` required
blockchain_status	string Payment order's internal status Validation Rules in :`pending,partial,mempool_unconfirmed,unconfirmed,paid,cancelled,expired,network_dispute,mempool_network_dispute,possible_chargeback,chargeback` required
unpaid	PaidStatus Payment order's unpaid amount Validation Rules required nullable

JSON Representation


{"_name": "payment_order_state", "_schema": {"blockchain_status": {"description": "Payment order\u0027s internal status", "rules": ["in:pending,partial,mempool_unconfirmed,unconfirmed,paid,cancelled,expired,network_dispute,mempool_network_dispute,possible_chargeback,chargeback", "required"], "type": "string"}, "in_confirmation": {"description": "Payment order\u0027s paid but unconfirmed amount", "rules": ["required", "nullable"], "type": "object(paid_status)"}, "paid": {"description": "Payment order\u0027s paid amount", "rules": ["required", "nullable"], "type": "object(paid_status)"}, "status": {"description": "Payment order\u0027s status", "rules": ["in:pending,paid,cancelled,expired,network_dispute,chargeback", "required"], "type": "string"}, "unpaid": {"description": "Payment order\u0027s unpaid amount", "rules": ["required", "nullable"], "type": "object(paid_status)"}}, "description": "Data describing the current state of a payment order", "expanded_schema": {"rules": [], "schema": {"blockchain_status": {"description": "Payment order\u0027s internal status", "rules": ["in:pending,partial,mempool_unconfirmed,unconfirmed,paid,cancelled,expired,network_dispute,mempool_network_dispute,possible_chargeback,chargeback", "required"], "type": "string"}, "in_confirmation": {"rules": ["nullable", "required"], "schema": {"crypto": {"description": "Cryto Amount", "rules": ["required"], "type": "integer"}, "fiat": {"description": "Fiat Amount", "rules": ["required", "decimal"], "type": "string"}}, "type": "object"}, "paid": {"rules": ["nullable", "required"], "schema": {"crypto": {"description": "Cryto Amount", "rules": ["required"], "type": "integer"}, "fiat": {"description": "Fiat Amount", "rules": ["required", "decimal"], "type": "string"}}, "type": "object"}, "status": {"description": "Payment order\u0027s status", "rules": ["in:pending,paid,cancelled,expired,network_dispute,chargeback", "required"], "type": "string"}, "unpaid": {"rules": ["nullable", "required"], "schema": {"crypto": {"description": "Cryto Amount", "rules": ["required"], "type": "integer"}, "fiat": {"description": "Fiat Amount", "rules": ["required", "decimal"], "type": "string"}}, "type": "object"}}, "type": "object"}, "rules": []}

PaidStatus

Cryto and fiat paid amounts

PROPERTIES
crypto	integer Cryto Amount Validation Rules required
fiat	string Fiat Amount Validation Rules required decimal

JSON Representation


{"_name": "paid_status", "_schema": {"crypto": {"description": "Cryto Amount", "rules": ["required"], "type": "integer"}, "fiat": {"description": "Fiat Amount", "rules": ["required", "decimal"], "type": "string"}}, "description": "Cryto and fiat paid amounts", "expanded_schema": {"rules": [], "schema": {"crypto": {"description": "Cryto Amount", "rules": ["required"], "type": "integer"}, "fiat": {"description": "Fiat Amount", "rules": ["required", "decimal"], "type": "string"}}, "type": "object"}, "rules": []}

Transaction

Bitcoin transaction paying a payment order

PROPERTIES
status	string Transaction's status Validation Rules required in :`unconfirmed,confirmed,reverted`
blockchain_status	string Transaction's internal status Validation Rules required in :`mempool,unconfirmed,confirmed,reverted`
created_at	ISO_8601_date Validation Rules required
normalized_txid	string Transaction's normalized id (DEPRECATED) Validation Rules len :`64` required
outs	array[Out] Transaction's outputs Validation Rules required
outs_sum	integer Paying amount of the transaction Validation Rules required
txid	string Transaction's id Validation Rules len :`64` required

JSON Representation


{"_name": "transaction", "_schema": {"blockchain_status": {"description": "Transaction\u0027s internal status", "rules": ["required", "in:mempool,unconfirmed,confirmed,reverted"], "type": "string"}, "created_at": {"description": "", "rules": ["required"], "type": "ISO_8601_date"}, "normalized_txid": {"description": "Transaction\u0027s normalized id (DEPRECATED)", "rules": ["len:64", "required"], "type": "string"}, "outs": {"description": "Transaction\u0027s outputs", "rules": ["required"], "type": "array[out]"}, "outs_sum": {"description": "Paying amount of the transaction", "rules": ["required"], "type": "integer"}, "status": {"description": "Transaction\u0027s status", "rules": ["required", "in:unconfirmed,confirmed,reverted"], "type": "string"}, "txid": {"description": "Transaction\u0027s id", "rules": ["len:64", "required"], "type": "string"}}, "description": "Bitcoin transaction paying a payment order", "expanded_schema": {"rules": [], "schema": {"blockchain_status": {"description": "Transaction\u0027s internal status", "rules": ["required", "in:mempool,unconfirmed,confirmed,reverted"], "type": "string"}, "created_at": {"description": "", "rules": ["required"], "type": "ISO_8601_date"}, "normalized_txid": {"description": "Transaction\u0027s normalized id (DEPRECATED)", "rules": ["len:64", "required"], "type": "string"}, "outs": {"elements": {"rules": [], "schema": {"amount": {"description": "Output\u0027s amount", "rules": ["required"], "type": "integer"}, "n": {"description": "Transaction output\u0027s index", "rules": ["required"], "type": "integer"}}, "type": "object"}, "rules": ["required"], "type": "array"}, "outs_sum": {"description": "Paying amount of the transaction", "rules": ["required"], "type": "integer"}, "status": {"description": "Transaction\u0027s status", "rules": ["required", "in:unconfirmed,confirmed,reverted"], "type": "string"}, "txid": {"description": "Transaction\u0027s id", "rules": ["len:64", "required"], "type": "string"}}, "type": "object"}, "rules": []}

Out

Transaction's output

PROPERTIES
amount	integer Output's amount Validation Rules required
n	integer Transaction output's index Validation Rules required

JSON Representation


{"_name": "out", "_schema": {"amount": {"description": "Output\u0027s amount", "rules": ["required"], "type": "integer"}, "n": {"description": "Transaction output\u0027s index", "rules": ["required"], "type": "integer"}}, "description": "Transaction\u0027s output", "expanded_schema": {"rules": [], "schema": {"amount": {"description": "Output\u0027s amount", "rules": ["required"], "type": "integer"}, "n": {"description": "Transaction output\u0027s index", "rules": ["required"], "type": "integer"}}, "type": "object"}, "rules": []}

PaymentOrderList

List of Business' payment orders

PROPERTIES
paymentorders	array[PaymentOrderRetrieval] Business' payment orders Validation Rules required nullable
total_pages	integer Total number of pages given the requested page size Validation Rules required
total_items	integer Total number of items Validation Rules required

JSON Representation


{"_name": "payment_order_list", "_schema": {"paymentorders": {"description": "Business\u0027 payment orders", "rules": ["required", "nullable"], "type": "array[payment_order_retrieval]"}, "total_items": {"description": "Total number of items", "rules": ["required"], "type": "integer"}, "total_pages": {"description": "Total number of pages given the requested page size", "rules": ["required"], "type": "integer"}}, "description": "List of Business\u0027 payment orders", "expanded_schema": {"rules": [], "schema": {"paymentorders": {"elements": {"rules": [], "schema": {"address": {"description": "Bitcoin address of the payment order", "rules": ["required"], "type": "base58"}, "amount": {"description": "Fiat\u0027s amount of the payment order", "rules": ["decimal", "required"], "type": "string"}, "btc_amount": {"description": " Bitcoin amount of the payment order", "rules": ["required"], "type": "integer"}, "callback_url": {"description": "The URL contacted to send callbacks related to payment status changes", "rules": ["regex[https_url]:^https://"], "type": "url"}, "chargeback_date": {"description": "Time at which either the payment order has been fully paid or is expired", "rules": ["required", "nullable"], "type": "ISO_8601_date"}, "created_at": {"description": "Creation date of the payment order", "rules": ["required"], "type": "ISO_8601_date"}, "created_by": {"rules": ["required"], "schema": {"active": {"description": "Wheter the creator active", "rules": [], "type": "boolean"}, "deposit_account": {"rules": ["required"], "schema": {"name": {"description": "Deposit account\u0027s name", "rules": ["required"], "type": "string"}, "type": {"description": "Deposit account\u0027s type", "rules": ["in:bank,bitcoin", "required"], "type": "string"}, "uuid": {"description": "Deposit account\u0027s uuid", "rules": ["required"], "type": "uuid"}}, "type": "object"}, "name": {"description": "Payment order creator\u0027s name", "rules": ["required"], "type": "string"}, "type": {"description": "Payment order creator\u0027s type", "rules": ["required", "in:web,mobile"], "type": "string"}, "uuid": {"description": "Payment order creator\u0027s uuid", "rules": ["required"], "type": "uuid"}}, "type": "object"}, "currency": {"rules": ["required"], "schema": {"name": {"description": "Name of the currency", "rules": ["required"], "type": "string"}, "type": {"description": "Currency\u0027s type (fiat/crypto)", "rules": ["in:crypto,fiat", "required"], "type": "string"}, "uuid": {"description": "UUID of the currency", "rules": ["required"], "type": "uuid"}}, "type": "object"}, "details": {"description": "Payment order\u0027s details", "rules": ["nullable"], "type": "string"}, "dispute_start_date": {"description": "Time at which either the payment order has been fully paid or is expired", "rules": ["required", "nullable"], "type": "ISO_8601_date"}, "expiration_time": {"description": "Expiration date of the payment order", "rules": ["required"], "type": "ISO_8601_date"}, "expires_in": {"description": " Expiration time of the payment order", "rules": ["required"], "type": "integer"}, "rate": {"rules": ["required"], "schema": {"created_at": {"description": "Creation\u0027s date of the rate", "rules": ["required"], "type": "ISO_8601_date"}, "from": {"description": "Starting currency for rate calculation", "rules": [], "type": "string"}, "source": {"description": "Exchange providing the rate", "rules": ["required"], "type": "string"}, "to": {"description": "Target currency for rate calculation", "rules": [], "type": "string"}, "value": {"description": "Value of the rate", "rules": ["decimal", "required"], "type": "string"}}, "type": "object"}, "redirect_url": {"description": "URL where to redirect the user to perform the payment", "rules": ["regex[https_url]:^https://"], "type": "url"}, "reference": {"description": "Business\u0027 reference for the payment order", "rules": ["nullable", "required"], "type": "string"}, "required_confirmations": {"description": "Required confirmations for transactions paying the payment order", "rules": ["required"], "type": "integer"}, "resolved_at": {"description": "Time at which either the payment order has been fully paid or is expired", "rules": ["required", "nullable"], "type": "ISO_8601_date"}, "state": {"rules": ["required"], "schema": {"blockchain_status": {"description": "Payment order\u0027s internal status", "rules": ["in:pending,partial,mempool_unconfirmed,unconfirmed,paid,cancelled,expired,network_dispute,mempool_network_dispute,possible_chargeback,chargeback", "required"], "type": "string"}, "in_confirmation": {"rules": ["nullable", "required"], "schema": {"crypto": {"description": "Cryto Amount", "rules": ["required"], "type": "integer"}, "fiat": {"description": "Fiat Amount", "rules": ["required", "decimal"], "type": "string"}}, "type": "object"}, "paid": {"rules": ["nullable", "required"], "schema": {"crypto": {"description": "Cryto Amount", "rules": ["required"], "type": "integer"}, "fiat": {"description": "Fiat Amount", "rules": ["required", "decimal"], "type": "string"}}, "type": "object"}, "status": {"description": "Payment order\u0027s status", "rules": ["in:pending,paid,cancelled,expired,network_dispute,chargeback", "required"], "type": "string"}, "unpaid": {"rules": ["nullable", "required"], "schema": {"crypto": {"description": "Cryto Amount", "rules": ["required"], "type": "integer"}, "fiat": {"description": "Fiat Amount", "rules": ["required", "decimal"], "type": "string"}}, "type": "object"}}, "type": "object"}, "transactions": {"elements": {"rules": [], "schema": {"blockchain_status": {"description": "Transaction\u0027s internal status", "rules": ["required", "in:mempool,unconfirmed,confirmed,reverted"], "type": "string"}, "created_at": {"description": "", "rules": ["required"], "type": "ISO_8601_date"}, "normalized_txid": {"description": "Transaction\u0027s normalized id (DEPRECATED)", "rules": ["len:64", "required"], "type": "string"}, "outs": {"elements": {"rules": [], "schema": {"amount": {"description": "Output\u0027s amount", "rules": ["required"], "type": "integer"}, "n": {"description": "Transaction output\u0027s index", "rules": ["required"], "type": "integer"}}, "type": "object"}, "rules": ["required"], "type": "array"}, "outs_sum": {"description": "Paying amount of the transaction", "rules": ["required"], "type": "integer"}, "status": {"description": "Transaction\u0027s status", "rules": ["required", "in:unconfirmed,confirmed,reverted"], "type": "string"}, "txid": {"description": "Transaction\u0027s id", "rules": ["len:64", "required"], "type": "string"}}, "type": "object"}, "rules": ["nullable", "required"], "type": "array"}, "uri": {"description": "Bitcoin uri", "rules": ["required"], "type": "string"}, "uuid": {"description": "UUID of the payment order", "rules": ["required"], "type": "uuid"}}, "type": "object"}, "rules": ["nullable", "required"], "type": "array"}, "total_items": {"description": "Total number of items", "rules": ["required"], "type": "integer"}, "total_pages": {"description": "Total number of pages given the requested page size", "rules": ["required"], "type": "integer"}}, "type": "object"}, "rules": []}

PaymentOrderCreation

Data required to create a new payment order

PROPERTIES
amount	string Payment order's fiat amount Validation Rules required decimal
cancel_url	url The URL where the user is redirected upon successful payment order expiration/cancellation Validation Rules regex :`https_url` nullable maxlen :`300`
continue_url	url The URL where the user is redirected upon successful payment Validation Rules regex :`https_url` nullable maxlen :`300`
callback_url	url The URL contacted to send callbacks related to payment status changes Validation Rules regex :`https_url` nullable maxlen :`300`
details	string Payment order's details Validation Rules maxlen :`300` nullable
reference	string Business' reference of the payment order Validation Rules maxlen :`300` nullable
required_confirmations	integer Required confirmations for transactions paying the payment order Validation Rules min :`0` nullable

JSON Representation


{"_name": "payment_order_creation", "_schema": {"amount": {"description": "Payment order\u0027s fiat amount", "rules": ["required", "decimal"], "type": "string"}, "callback_url": {"description": "The URL contacted to send callbacks related to payment status changes", "rules": ["regex[https_url]:^https://", "nullable", "maxlen:300"], "type": "url"}, "cancel_url": {"description": "The URL where the user is redirected upon successful payment order expiration/cancellation", "rules": ["regex[https_url]:^https://", "nullable", "maxlen:300"], "type": "url"}, "continue_url": {"description": "The URL where the user is redirected upon successful payment", "rules": ["regex[https_url]:^https://", "nullable", "maxlen:300"], "type": "url"}, "details": {"description": "Payment order\u0027s details", "rules": ["maxlen:300", "nullable"], "type": "string"}, "reference": {"description": "Business\u0027 reference of the payment order", "rules": ["maxlen:300", "nullable"], "type": "string"}, "required_confirmations": {"description": "Required confirmations for transactions paying the payment order", "rules": ["min:0", "nullable"], "type": "integer"}}, "description": "Data required to create a new payment order", "expanded_schema": {"rules": [], "schema": {"amount": {"description": "Payment order\u0027s fiat amount", "rules": ["required", "decimal"], "type": "string"}, "callback_url": {"description": "The URL contacted to send callbacks related to payment status changes", "rules": ["regex[https_url]:^https://", "nullable", "maxlen:300"], "type": "url"}, "cancel_url": {"description": "The URL where the user is redirected upon successful payment order expiration/cancellation", "rules": ["regex[https_url]:^https://", "nullable", "maxlen:300"], "type": "url"}, "continue_url": {"description": "The URL where the user is redirected upon successful payment", "rules": ["regex[https_url]:^https://", "nullable", "maxlen:300"], "type": "url"}, "details": {"description": "Payment order\u0027s details", "rules": ["maxlen:300", "nullable"], "type": "string"}, "reference": {"description": "Business\u0027 reference of the payment order", "rules": ["maxlen:300", "nullable"], "type": "string"}, "required_confirmations": {"description": "Required confirmations for transactions paying the payment order", "rules": ["min:0", "nullable"], "type": "integer"}}, "type": "object"}, "rules": []}

PaymentOrderCreationResponse

Response data for a payment order creation request

PROPERTIES
address	string Bitcoin address of the payment order Validation Rules regex :`^` required
amount	integer Crypto amount of the payment order Validation Rules required
expiration_time	ISO_8601_date Expiration's date of the payment order Validation Rules required
expires_in	integer Expiration's time of the payment order Validation Rules required
rate	RateRetrieval Crypto/Fiat rate of the payment order Validation Rules required
redirect_url	url URL where to redirect the user to perform the payment Validation Rules regex :`https_url` required nullable
uri	string Bitcoin uri according to BIP 21 (https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki) Validation Rules regex :`^` required
uuid	uuid UUID of the payment order Validation Rules required
created_at	ISO_8601_date Creation date of the payment order Validation Rules nullable
reference	string Payment Order reference Validation Rules nullable

JSON Representation


{"_name": "payment_order_creation_response", "_schema": {"address": {"description": "Bitcoin address of the payment order", "rules": ["regex:^", "required"], "type": "string"}, "amount": {"description": "Crypto amount of the payment order", "rules": ["required"], "type": "integer"}, "created_at": {"description": "Creation date of the payment order", "rules": ["nullable"], "type": "ISO_8601_date"}, "expiration_time": {"description": "Expiration\u0027s date of the payment order", "rules": ["required"], "type": "ISO_8601_date"}, "expires_in": {"description": "Expiration\u0027s time of the payment order", "rules": ["required"], "type": "integer"}, "rate": {"description": "Crypto/Fiat rate of the payment order", "rules": ["required"], "type": "object(rate_retrieval)"}, "redirect_url": {"description": "URL where to redirect the user to perform the payment", "rules": ["regex[https_url]:^https://", "required", "nullable"], "type": "url"}, "reference": {"description": "Payment Order reference", "rules": ["nullable"], "type": "string"}, "uri": {"description": "Bitcoin uri according to BIP 21 (https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki)", "rules": ["regex:^", "required"], "type": "string"}, "uuid": {"description": "UUID of the payment order", "rules": ["required"], "type": "uuid"}}, "description": "Response data for a payment order creation request", "expanded_schema": {"rules": [], "schema": {"address": {"description": "Bitcoin address of the payment order", "rules": ["regex:^", "required"], "type": "string"}, "amount": {"description": "Crypto amount of the payment order", "rules": ["required"], "type": "integer"}, "created_at": {"description": "Creation date of the payment order", "rules": ["nullable"], "type": "ISO_8601_date"}, "expiration_time": {"description": "Expiration\u0027s date of the payment order", "rules": ["required"], "type": "ISO_8601_date"}, "expires_in": {"description": "Expiration\u0027s time of the payment order", "rules": ["required"], "type": "integer"}, "rate": {"rules": ["required"], "schema": {"created_at": {"description": "Creation\u0027s date of the rate", "rules": ["required"], "type": "ISO_8601_date"}, "from": {"description": "Starting currency for rate calculation", "rules": [], "type": "string"}, "source": {"description": "Exchange providing the rate", "rules": ["required"], "type": "string"}, "to": {"description": "Target currency for rate calculation", "rules": [], "type": "string"}, "value": {"description": "Value of the rate", "rules": ["decimal", "required"], "type": "string"}}, "type": "object"}, "redirect_url": {"description": "URL where to redirect the user to perform the payment", "rules": ["regex[https_url]:^https://", "required", "nullable"], "type": "url"}, "reference": {"description": "Payment Order reference", "rules": ["nullable"], "type": "string"}, "uri": {"description": "Bitcoin uri according to BIP 21 (https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki)", "rules": ["regex:^", "required"], "type": "string"}, "uuid": {"description": "UUID of the payment order", "rules": ["required"], "type": "uuid"}}, "type": "object"}, "rules": []}

CallbackList

Callback list object

PROPERTIES
callbacks	array[Callback] Valid payment transitions callbacks Validation Rules required

JSON Representation


{"_name": "callback_list", "_schema": {"callbacks": {"description": "Valid payment transitions callbacks", "rules": ["required"], "type": "array[callback]"}}, "description": "Callback list object", "expanded_schema": {"rules": [], "schema": {"callbacks": {"elements": {"rules": [], "schema": {"name": {"description": "Namespace of a callback sent after the related payment status\u0027 transition", "rules": ["required"], "type": "string"}}, "type": "object"}, "rules": ["required"], "type": "array"}}, "type": "object"}, "rules": []}

Callback

Callback Retrieval object

PROPERTIES
name	string Namespace of a callback sent after the related payment status' transition Validation Rules required

JSON Representation


{"_name": "callback", "_schema": {"name": {"description": "Namespace of a callback sent after the related payment status\u0027 transition", "rules": ["required"], "type": "string"}}, "description": "Callback Retrieval object", "expanded_schema": {"rules": [], "schema": {"name": {"description": "Namespace of a callback sent after the related payment status\u0027 transition", "rules": ["required"], "type": "string"}}, "type": "object"}, "rules": []}

PaymentUpdateObject

Callback's trigger request body

PROPERTIES
callback	string Name of the callback to be sent Validation Rules required

JSON Representation


{"_name": "payment_update_object", "_schema": {"callback": {"description": "Name of the callback to be sent", "rules": ["required"], "type": "string"}}, "description": "Callback\u0027s trigger request body", "expanded_schema": {"rules": [], "schema": {"callback": {"description": "Name of the callback to be sent", "rules": ["required"], "type": "string"}}, "type": "object"}, "rules": []}

CallbackPaymentOrder

Payment order retrieval data

PROPERTIES
address	base58 Bitcoin address of the payment order Validation Rules required
amount	string Fiat's amount of the payment order Validation Rules decimal required
btc_amount	integer Bitcoin amount of the payment order Validation Rules required
cancel_url	url The URL where the user is redirected upon payment order expiration/cancellation Validation Rules regex :`https_url` required
continue_url	url The URL where the user is redirected upon successful payment Validation Rules regex :`https_url` required
callback_url	url The URL contacted to send callbacks related to payment status changes Validation Rules regex :`https_url` required
created_at	ISO_8601_date Creation date of the payment order Validation Rules required
created_by	PaymentOrderCreator Data of the pos which created the payment order Validation Rules required
currency	CurrencyRetrieval Fiat currency of the payment order Validation Rules required
details	string Payment order's details Validation Rules required nullable
expiration_time	ISO_8601_date Expiration date of the payment order Validation Rules required
expires_in	integer Expiration time of the payment order Validation Rules required
rate	RateRetrieval Crypto/Fiat rate of the payment order Validation Rules required
redirect_url	url URL where to redirect the user to perform the payment Validation Rules regex :`https_url` required
reference	string Business' reference for the payment order Validation Rules nullable required
required_confirmations	integer Required confirmations for transactions paying the payment order Validation Rules required
resolved_at	ISO_8601_date Time at which either the payment order has been fully paid or is expired Validation Rules required nullable
state	PaymentOrderState Current payment state of the payment order Validation Rules required
transactions	array[Transaction] Transactions paying the payment order Validation Rules nullable required
dispute_start_date	ISO_8601_date Time at which either the payment order has been fully paid or is expired Validation Rules required nullable
chargeback_date	ISO_8601_date Time at which either the payment order has been fully paid or is expired Validation Rules required nullable
uri	string Bitcoin uri Validation Rules required
uuid	uuid UUID of the payment order Validation Rules required

JSON Representation


{"_name": "callback_payment_order", "_schema": {"address": {"description": "Bitcoin address of the payment order", "rules": ["required"], "type": "base58"}, "amount": {"description": "Fiat\u0027s amount of the payment order", "rules": ["decimal", "required"], "type": "string"}, "btc_amount": {"description": " Bitcoin amount of the payment order", "rules": ["required"], "type": "integer"}, "callback_url": {"description": "The URL contacted to send callbacks related to payment status changes", "rules": ["regex[https_url]:^https://", "required"], "type": "url"}, "cancel_url": {"description": "The URL where the user is redirected upon payment order expiration/cancellation", "rules": ["regex[https_url]:^https://", "required"], "type": "url"}, "chargeback_date": {"description": "Time at which either the payment order has been fully paid or is expired", "rules": ["required", "nullable"], "type": "ISO_8601_date"}, "continue_url": {"description": "The URL where the user is redirected upon successful payment", "rules": ["regex[https_url]:^https://", "required"], "type": "url"}, "created_at": {"description": "Creation date of the payment order", "rules": ["required"], "type": "ISO_8601_date"}, "created_by": {"description": "Data of the pos which created the payment order", "rules": ["required"], "type": "object(payment_order_creator)"}, "currency": {"description": "Fiat currency of the payment order", "rules": ["required"], "type": "object(currency_retrieval)"}, "details": {"description": "Payment order\u0027s details", "rules": ["required", "nullable"], "type": "string"}, "dispute_start_date": {"description": "Time at which either the payment order has been fully paid or is expired", "rules": ["required", "nullable"], "type": "ISO_8601_date"}, "expiration_time": {"description": "Expiration date of the payment order", "rules": ["required"], "type": "ISO_8601_date"}, "expires_in": {"description": " Expiration time of the payment order", "rules": ["required"], "type": "integer"}, "rate": {"description": "Crypto/Fiat rate of the payment order", "rules": ["required"], "type": "object(rate_retrieval)"}, "redirect_url": {"description": "URL where to redirect the user to perform the payment", "rules": ["regex[https_url]:^https://", "required"], "type": "url"}, "reference": {"description": "Business\u0027 reference for the payment order", "rules": ["nullable", "required"], "type": "string"}, "required_confirmations": {"description": "Required confirmations for transactions paying the payment order", "rules": ["required"], "type": "integer"}, "resolved_at": {"description": "Time at which either the payment order has been fully paid or is expired", "rules": ["required", "nullable"], "type": "ISO_8601_date"}, "state": {"description": "Current payment state of the payment order", "rules": ["required"], "type": "object(payment_order_state)"}, "transactions": {"description": "Transactions paying the payment order", "rules": ["nullable", "required"], "type": "array[transaction]"}, "uri": {"description": "Bitcoin uri", "rules": ["required"], "type": "string"}, "uuid": {"description": "UUID of the payment order", "rules": ["required"], "type": "uuid"}}, "description": "Payment order retrieval data", "expanded_schema": {"rules": [], "schema": {"address": {"description": "Bitcoin address of the payment order", "rules": ["required"], "type": "base58"}, "amount": {"description": "Fiat\u0027s amount of the payment order", "rules": ["decimal", "required"], "type": "string"}, "btc_amount": {"description": " Bitcoin amount of the payment order", "rules": ["required"], "type": "integer"}, "callback_url": {"description": "The URL contacted to send callbacks related to payment status changes", "rules": ["regex[https_url]:^https://", "required"], "type": "url"}, "cancel_url": {"description": "The URL where the user is redirected upon payment order expiration/cancellation", "rules": ["regex[https_url]:^https://", "required"], "type": "url"}, "chargeback_date": {"description": "Time at which either the payment order has been fully paid or is expired", "rules": ["required", "nullable"], "type": "ISO_8601_date"}, "continue_url": {"description": "The URL where the user is redirected upon successful payment", "rules": ["regex[https_url]:^https://", "required"], "type": "url"}, "created_at": {"description": "Creation date of the payment order", "rules": ["required"], "type": "ISO_8601_date"}, "created_by": {"rules": ["required"], "schema": {"active": {"description": "Wheter the creator active", "rules": [], "type": "boolean"}, "deposit_account": {"rules": ["required"], "schema": {"name": {"description": "Deposit account\u0027s name", "rules": ["required"], "type": "string"}, "type": {"description": "Deposit account\u0027s type", "rules": ["in:bank,bitcoin", "required"], "type": "string"}, "uuid": {"description": "Deposit account\u0027s uuid", "rules": ["required"], "type": "uuid"}}, "type": "object"}, "name": {"description": "Payment order creator\u0027s name", "rules": ["required"], "type": "string"}, "type": {"description": "Payment order creator\u0027s type", "rules": ["required", "in:web,mobile"], "type": "string"}, "uuid": {"description": "Payment order creator\u0027s uuid", "rules": ["required"], "type": "uuid"}}, "type": "object"}, "currency": {"rules": ["required"], "schema": {"name": {"description": "Name of the currency", "rules": ["required"], "type": "string"}, "type": {"description": "Currency\u0027s type (fiat/crypto)", "rules": ["in:crypto,fiat", "required"], "type": "string"}, "uuid": {"description": "UUID of the currency", "rules": ["required"], "type": "uuid"}}, "type": "object"}, "details": {"description": "Payment order\u0027s details", "rules": ["required", "nullable"], "type": "string"}, "dispute_start_date": {"description": "Time at which either the payment order has been fully paid or is expired", "rules": ["required", "nullable"], "type": "ISO_8601_date"}, "expiration_time": {"description": "Expiration date of the payment order", "rules": ["required"], "type": "ISO_8601_date"}, "expires_in": {"description": " Expiration time of the payment order", "rules": ["required"], "type": "integer"}, "rate": {"rules": ["required"], "schema": {"created_at": {"description": "Creation\u0027s date of the rate", "rules": ["required"], "type": "ISO_8601_date"}, "from": {"description": "Starting currency for rate calculation", "rules": [], "type": "string"}, "source": {"description": "Exchange providing the rate", "rules": ["required"], "type": "string"}, "to": {"description": "Target currency for rate calculation", "rules": [], "type": "string"}, "value": {"description": "Value of the rate", "rules": ["decimal", "required"], "type": "string"}}, "type": "object"}, "redirect_url": {"description": "URL where to redirect the user to perform the payment", "rules": ["regex[https_url]:^https://", "required"], "type": "url"}, "reference": {"description": "Business\u0027 reference for the payment order", "rules": ["nullable", "required"], "type": "string"}, "required_confirmations": {"description": "Required confirmations for transactions paying the payment order", "rules": ["required"], "type": "integer"}, "resolved_at": {"description": "Time at which either the payment order has been fully paid or is expired", "rules": ["required", "nullable"], "type": "ISO_8601_date"}, "state": {"rules": ["required"], "schema": {"blockchain_status": {"description": "Payment order\u0027s internal status", "rules": ["in:pending,partial,mempool_unconfirmed,unconfirmed,paid,cancelled,expired,network_dispute,mempool_network_dispute,possible_chargeback,chargeback", "required"], "type": "string"}, "in_confirmation": {"rules": ["nullable", "required"], "schema": {"crypto": {"description": "Cryto Amount", "rules": ["required"], "type": "integer"}, "fiat": {"description": "Fiat Amount", "rules": ["required", "decimal"], "type": "string"}}, "type": "object"}, "paid": {"rules": ["nullable", "required"], "schema": {"crypto": {"description": "Cryto Amount", "rules": ["required"], "type": "integer"}, "fiat": {"description": "Fiat Amount", "rules": ["required", "decimal"], "type": "string"}}, "type": "object"}, "status": {"description": "Payment order\u0027s status", "rules": ["in:pending,paid,cancelled,expired,network_dispute,chargeback", "required"], "type": "string"}, "unpaid": {"rules": ["nullable", "required"], "schema": {"crypto": {"description": "Cryto Amount", "rules": ["required"], "type": "integer"}, "fiat": {"description": "Fiat Amount", "rules": ["required", "decimal"], "type": "string"}}, "type": "object"}}, "type": "object"}, "transactions": {"elements": {"rules": [], "schema": {"blockchain_status": {"description": "Transaction\u0027s internal status", "rules": ["required", "in:mempool,unconfirmed,confirmed,reverted"], "type": "string"}, "created_at": {"description": "", "rules": ["required"], "type": "ISO_8601_date"}, "normalized_txid": {"description": "Transaction\u0027s normalized id (DEPRECATED)", "rules": ["len:64", "required"], "type": "string"}, "outs": {"elements": {"rules": [], "schema": {"amount": {"description": "Output\u0027s amount", "rules": ["required"], "type": "integer"}, "n": {"description": "Transaction output\u0027s index", "rules": ["required"], "type": "integer"}}, "type": "object"}, "rules": ["required"], "type": "array"}, "outs_sum": {"description": "Paying amount of the transaction", "rules": ["required"], "type": "integer"}, "status": {"description": "Transaction\u0027s status", "rules": ["required", "in:unconfirmed,confirmed,reverted"], "type": "string"}, "txid": {"description": "Transaction\u0027s id", "rules": ["len:64", "required"], "type": "string"}}, "type": "object"}, "rules": ["nullable", "required"], "type": "array"}, "uri": {"description": "Bitcoin uri", "rules": ["required"], "type": "string"}, "uuid": {"description": "UUID of the payment order", "rules": ["required"], "type": "uuid"}}, "type": "object"}, "rules": []}

Errors

Error List

Error Code	Type	HTTP Status Code	Description
0001	`Validation Error`	`422 Unprocessable Entity`	The request body is invalid. Further informations are available in the error response
0013	`Invalid Callback`	`422 Unprocessable Entity`	The requested callback is invalid for the current payment state
1001	`Unauthorized Client`	`401 Unauthorized`	Client performing the request is unauthorized (wrong client id/secret)
1002	`Invalid Grant Type`	`401 Unauthorized`	Grant type used to perform authentication not supported
1004	`Access Token Expired`	`401 Unauthorized`	The access token is expired
1006	`Invalid Refresh Token`	`401 Unauthorized`	The provided refresh token does not exist
1007	`Invalid Access Token`	`401 Unauthorized`	The provided access token does not exist
1012	`Forbidden`	`403 Forbidden`	The user has no permission to perform the request
1013	`Invalid Scope`	`401 Unauthorized`	The requested scope is invalid (either does not exist or is not available for the client)
1018	`Invalid Realm`	`401 Unauthorized`	Client is not authorized to perform requests on this realm (sandbox/live)
2000	`Too Many Requests`	`429 Too Many Requests`	Rate limit exceeded
3001	`Not Found`	`404 Not Found`	Requested resource does not exists
3003	`Method Not Allowed`	`405 Method Not Allowed`	The endpoint does not expose the requested http method
3007	`Invalid Authorization Header`	`401 Unauthorized`	The authorization header is malformed (Format: Authorization: Basic/Bearer {value})
3012	`Invalid Content Type Header`	`412 Precondition Failed`	The Content Type header is invalid (either is malformed or its value is invalid for the request)
3013	`Invalid Accept Header`	`412 Precondition Failed`	The Accept header is invalid (either is malformed or its value is invalid for the request)
4000	`Internal Server Error`	`500 Internal Server Error`	An internal server error has occurred
4003	`Rate Unavailable`	`503 Service Unavailable`	An accurate Rate is unavailable
4006	`Functionality Down`	`503 Service Unavailable`	The functionality is temporarily down

Error Responses

Error responses are returned in json format and they contain the following fields:

error_code: The internal error code

message: Short description of the error