Developers > webPOS API

API Version1.0

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:

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

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.
3. The payment order regains enough confirmed bitcoin transactions to cover for its required amount.
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
X-RateLimit-Remaining Number of remaining allowed requests per second
X-RateLimit-Reset Remaining time (in seconds) for the rate limits to reset
X-RateLimit-Limit Number of allowed requests per second
Access-Control-Allow-Headers Headers allowed for the request
Access-Control-Allow-Methods Methods allowed for the request
Access-Control-Allow-Origin Origin allowed to perform the request
Access-Control-Allow-Credentials Whether the request can be performed using credentials (Cookies/Authorization Header/TLS client certificates)

Validation Rules

Validation Rule Description
equals The value must be equal to the given one
maxlen The value's length must not exceed the given maximum
nullable_if The value can be null if the given condition applies
hex The value must be hexadecimal
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 (.)
minlen The value's length must not be lower than the given minimum
betweenlen The value's length must be in the given range
alpha The value must contain only alphabetic characters
alphanum The value must be alphanumeric
equals_to The value must be equal to the one of the given object field
in The value must be one of the given list ov values
regex The value must be conform to the given regex
between The value must be in the given range
max The value must not exceed the given maximum
alphadash The value must contain only alphabetic or dash (-) characters
required The value is required
min The value must not be lower than the given minimum
nullable The value can be null
len The value's len must be of the given one

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

Tags

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:

Endpoints

Authentication

Endpoints to handle authentication

Client Credentials Login

Endpoint to sign in the system

Tags: Authenticating

Request
URI
POST
/token
Header Parameters
Accept application/json
Content-Type application/x-www-form-urlencoded
Authorization Basic b64(client_id:client_secret)
Body Parameters
scope string
Oauth2 scope of the client's authorization

Validation Rules
in: *
required
grant_type string
Oauth2 Authorization's grant type

Validation Rules
equals: client_credentials
required
Response
200 OK
Headers
Content-Type application/json
Body Parameters
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
expires_in integer
Token's expiration time

Validation Rules
required
scope string
Authorization's scope

Validation Rules
nullable
access_token string
User's access token

Validation Rules
required
Code Example
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);
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
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();

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
Accept application/json
Content-Type 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
Code Example
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}");
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}')
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();

Get Payment Order

Endpoint to retrieve a payment order

Tags: Authenticated

Request
URI
GET
/payment-order/{payment_order_uuid}
Header Parameters
Accept application/json
Content-Type application/json
URI params
payment_order_uuid uuid

Validation Rules
required
Response
200 OK
Headers
Content-Type application/json
Body Parameters
expiration_time ISO_8601_date
Expiration date of the payment order

Validation Rules
required
rate RateRetrieval
Crypto/Fiat rate of the payment order

Validation Rules
required
address base58
Bitcoin address of the payment order

Validation Rules
required
created_by PaymentOrderCreator
Data of the pos which created the payment order

Validation Rules
required
uri string
Bitcoin uri

Validation Rules
required
expires_in integer
Expiration time of the payment order

Validation Rules
required
state PaymentOrderState
Current payment state of the payment order

Validation Rules
required
transactions array[Transaction]
Transactions paying the payment order

Validation Rules
nullable
required
uuid uuid
UUID of the payment order

Validation Rules
required
chargeback_date ISO_8601_date
Time at which either the payment order has been fully paid or is expired

Validation Rules
required
nullable
required_confirmations integer
Required confirmations for transactions paying the payment order

Validation Rules
required
reference string
Business' reference for the payment order

Validation Rules
nullable
required
resolved_at ISO_8601_date
Time at which either the payment order has been fully paid or is expired

Validation Rules
required
nullable
redirect_url url
URL where to redirect the user to perform the payment

Validation Rules
regex[https_url]: ^https://
required
amount string
Fiat's amount of the payment order

Validation Rules
decimal
required
currency CurrencyRetrieval
Fiat currency of the payment order

Validation Rules
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
btc_amount integer
Bitcoin amount of the payment order

Validation Rules
required
details string
Payment order's details

Validation Rules
required
nullable
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
Possible Errors
Code Example
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}");
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
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();

Get Payment Orders

Endpoint to retrieve all business' payment orders

Tags: Authenticated

Request
URI
GET
/payment-order
Header Parameters
Accept application/json
Content-Type 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_order string
Ordering to be used for the sort (default: desc)

Validation Rules
in: asc,desc
nullable
sort_by string
Field used to sort pages (default: created_at)

Validation Rules
in: amount,created_at
nullable
page_size integer
Size of the returned page (default: 20)

Validation Rules
nullable
max: 40
page integer
Index of the page to be returned (default: 0)

Validation Rules
nullable
min: 0
Response
200 OK
Headers
Content-Type application/json
Body Parameters
total_items integer
Total number of items

Validation Rules
required
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

Create Payment Order

Endpoint to create a new payment order

Tags: Authenticated

Request
URI
POST
/payment-order
Header Parameters
Accept application/json
Content-Type application/json
Body Parameters
continue_url url
The URL where the user is redirected upon successful payment

Validation Rules
regex[https_url]: ^https://
nullable
maxlen: 300
required_confirmations integer
Required confirmations for transactions paying the payment order

Validation Rules
min: 0
nullable
reference string
Business' reference of the payment order

Validation Rules
maxlen: 300
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
details string
Payment order's details

Validation Rules
required
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
amount string
Payment order's fiat amount

Validation Rules
required
decimal
Response
201 Created
Headers
Content-Type application/json
Body Parameters
uuid uuid
UUID of the payment order

Validation Rules
required
expiration_time ISO_8601_date
Expiration's date of the payment order

Validation Rules
required
rate RateRetrieval
Crypto/Fiat rate of the payment order

Validation Rules
required
address string
Bitcoin address of the payment order

Validation Rules
regex: ^
required
amount integer
Crypto amount of the payment order

Validation Rules
required
expires_in integer
Expiration's time of the payment order

Validation Rules
required
uri string
Bitcoin uri according to BIP 21 (https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki)

Validation Rules
regex: ^
required
redirect_url url
URL where to redirect the user to perform the payment

Validation Rules
regex[https_url]: ^https://
required
nullable
Code Example
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
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
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();

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.completed
object object
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

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

PaymentCompleted

event payment.completed
object CallbackPaymentOrder

PaymentDisputeStart

event payment.dispute.start
object CallbackPaymentOrder

PaymentOverpaid

event payment.overpaid
object CallbackPaymentOrder

PaymentCancelled

event payment.cancelled
object CallbackPaymentOrder

PaymentDisputeEnd

event payment.dispute.end
object CallbackPaymentOrder

PaymentExpired

event payment.expired
object CallbackPaymentOrder

PaymentChargeback

event payment.chargeback
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
Accept application/json
Content-Type 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
Code Example
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}");
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}')

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
Accept application/json
Content-Type application/json
URI params
payment_order_uuid uuid

Validation Rules
required
Response
200 OK
Headers
Content-Type application/json
Body Parameters
expiration_time ISO_8601_date
Expiration date of the payment order

Validation Rules
required
rate RateRetrieval
Crypto/Fiat rate of the payment order

Validation Rules
required
address base58
Bitcoin address of the payment order

Validation Rules
required
created_by PaymentOrderCreator
Data of the pos which created the payment order

Validation Rules
required
uri string
Bitcoin uri

Validation Rules
required
expires_in integer
Expiration time of the payment order

Validation Rules
required
state PaymentOrderState
Current payment state of the payment order

Validation Rules
required
transactions array[Transaction]
Transactions paying the payment order

Validation Rules
nullable
required
uuid uuid
UUID of the payment order

Validation Rules
required
chargeback_date ISO_8601_date
Time at which either the payment order has been fully paid or is expired

Validation Rules
required
nullable
required_confirmations integer
Required confirmations for transactions paying the payment order

Validation Rules
required
reference string
Business' reference for the payment order

Validation Rules
nullable
required
resolved_at ISO_8601_date
Time at which either the payment order has been fully paid or is expired

Validation Rules
required
nullable
redirect_url url
URL where to redirect the user to perform the payment

Validation Rules
regex[https_url]: ^https://
required
amount string
Fiat's amount of the payment order

Validation Rules
decimal
required
currency CurrencyRetrieval
Fiat currency of the payment order

Validation Rules
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
btc_amount integer
Bitcoin amount of the payment order

Validation Rules
required
details string
Payment order's details

Validation Rules
required
nullable
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
Possible Errors
Code Example
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
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}')

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
Accept application/json
Content-Type 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
Code Example
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
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)

Types

Primitive Types

Primitive Types List
  • string
  • boolean
  • integer

Custom Types

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

base58

Base 58 encoded string

Base Type string
regex
Example None

url

Url field

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

base64

Base 64 encoded string

Base Type string
regex
Example None

email

Email field

Base Type string
regex
Example user@domain.com

ISO_8601_date

Date field

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

Objects

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": []}

PaymentOrderRetrieval

Payment order retrieval data

PROPERTIES
expiration_time ISO_8601_date
Expiration date of the payment order

Validation Rules
required
rate RateRetrieval
Crypto/Fiat rate of the payment order

Validation Rules
required
address base58
Bitcoin address of the payment order

Validation Rules
required
created_by PaymentOrderCreator
Data of the pos which created the payment order

Validation Rules
required
uri string
Bitcoin uri

Validation Rules
required
expires_in integer
Expiration time of the payment order

Validation Rules
required
state PaymentOrderState
Current payment state of the payment order

Validation Rules
required
transactions array[Transaction]
Transactions paying the payment order

Validation Rules
nullable
required
uuid uuid
UUID of the payment order

Validation Rules
required
chargeback_date ISO_8601_date
Time at which either the payment order has been fully paid or is expired

Validation Rules
required
nullable
required_confirmations integer
Required confirmations for transactions paying the payment order

Validation Rules
required
reference string
Business' reference for the payment order

Validation Rules
nullable
required
resolved_at ISO_8601_date
Time at which either the payment order has been fully paid or is expired

Validation Rules
required
nullable
redirect_url url
URL where to redirect the user to perform the payment

Validation Rules
regex :https_url
required
amount string
Fiat's amount of the payment order

Validation Rules
decimal
required
currency CurrencyRetrieval
Fiat currency of the payment order

Validation Rules
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
btc_amount integer
Bitcoin amount of the payment order

Validation Rules
required
details string
Payment order's details

Validation Rules
required
nullable
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
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://", "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"}, "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"}, "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": {"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"], "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"}, "source": {"description": "Exchange providing the rate", "rules": ["required"], "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": ["required", "nullable"], "schema": {"crypto": {"description": "Cryto Amount", "rules": ["required"], "type": "integer"}, "fiat": {"description": "Fiat Amount", "rules": ["required", "decimal"], "type": "string"}}, "type": "object"}, "paid": {"rules": ["required", "nullable"], "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": ["required", "nullable"], "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", "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": ["required", "nullable"], "type": "array"}, "uri": {"description": "Bitcoin uri", "rules": ["required"], "type": "string"}, "uuid": {"description": "UUID of the payment order", "rules": ["required"], "type": "uuid"}}, "type": "object"}, "rules": []}

RateRetrieval

Rate Data

PROPERTIES
value string
Value of the rate

Validation Rules
decimal
required
created_at ISO_8601_date
Creation's date of the rate

Validation Rules
required
source string
Exchange providing the rate

Validation Rules
required
JSON Representation
{"_name": "rate_retrieval", "_schema": {"created_at": {"description": "Creation\u0027s date of the rate", "rules": ["required"], "type": "ISO_8601_date"}, "source": {"description": "Exchange providing the rate", "rules": ["required"], "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"}, "source": {"description": "Exchange providing the rate", "rules": ["required"], "type": "string"}, "value": {"description": "Value of the rate", "rules": ["decimal", "required"], "type": "string"}}, "type": "object"}, "rules": []}

PaymentOrderCreator

Data of payment order's creator

PROPERTIES
type string
Payment order creator's type

Validation Rules
required
in :web
uuid uuid
Payment order creator's uuid

Validation Rules
required
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
JSON Representation
{"_name": "payment_order_creator", "_schema": {"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"], "type": "string"}, "uuid": {"description": "Payment order creator\u0027s uuid", "rules": ["required"], "type": "uuid"}}, "description": "Data of payment order\u0027s creator", "expanded_schema": {"rules": [], "schema": {"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"], "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
type string
Deposit account's type

Validation Rules
in :bank,bitcoin
required
uuid uuid
Deposit account's uuid

Validation Rules
required
name string
Deposit account's name

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": []}

PaymentOrderState

Data describing the current state of a payment order

PROPERTIES
unpaid PaidStatus
Payment order's unpaid amount

Validation Rules
required
nullable
in_confirmation PaidStatus
Payment order's paid but unconfirmed 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
paid PaidStatus
Payment order's paid 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": ["required", "nullable"], "schema": {"crypto": {"description": "Cryto Amount", "rules": ["required"], "type": "integer"}, "fiat": {"description": "Fiat Amount", "rules": ["required", "decimal"], "type": "string"}}, "type": "object"}, "paid": {"rules": ["required", "nullable"], "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": ["required", "nullable"], "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
fiat string
Fiat Amount

Validation Rules
required
decimal
crypto integer
Cryto Amount

Validation Rules
required
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
outs_sum integer
Paying amount of the transaction

Validation Rules
required
outs array[Out]
Transaction's outputs

Validation Rules
required
blockchain_status string
Transaction's internal status

Validation Rules
required
in :mempool,unconfirmed,confirmed,reverted
normalized_txid string
Transaction's normalized id

Validation Rules
len :64
required
created_at ISO_8601_date


Validation Rules
required
status string
Transaction's status

Validation Rules
required
in :unconfirmed,confirmed,reverted
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", "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", "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
n integer
Transaction output's index

Validation Rules
required
amount integer
Output's amount

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": []}

CurrencyRetrieval

Currency Data

PROPERTIES
type string
Currency's type (fiat/crypto)

Validation Rules
in :crypto,fiat
required
uuid uuid
UUID of the currency

Validation Rules
required
name string
Name 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": []}

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": []}

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": []}

PaymentOrderList

List of Business' payment orders

PROPERTIES
total_items integer
Total number of items

Validation Rules
required
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
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://", "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"}, "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 is ctive", "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"], "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": ["required", "nullable"], "schema": {"crypto": {"description": "Cryto Amount", "rules": ["required"], "type": "integer"}, "fiat": {"description": "Fiat Amount", "rules": ["required", "decimal"], "type": "string"}}, "type": "object"}, "paid": {"rules": ["required", "nullable"], "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": ["required", "nullable"], "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", "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": ["required", "nullable"], "type": "array"}, "uri": {"description": "Bitcoin uri", "rules": ["required"], "type": "string"}, "uuid": {"description": "UUID of the payment order", "rules": ["required"], "type": "uuid"}}, "type": "object"}, "rules": ["required", "nullable"], "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
continue_url url
The URL where the user is redirected upon successful payment

Validation Rules
regex :https_url
nullable
maxlen :300
required_confirmations integer
Required confirmations for transactions paying the payment order

Validation Rules
min :0
nullable
reference string
Business' reference of the payment order

Validation Rules
maxlen :300
cancel_url url
The URL where the user is redirected upon successful payment order expiration/cancellation

Validation Rules
regex :https_url
nullable
maxlen :300
details string
Payment order's details

Validation Rules
required
maxlen :300
callback_url url
The URL contacted to send callbacks related to payment status changes

Validation Rules
regex :https_url
nullable
maxlen :300
amount string
Payment order's fiat amount

Validation Rules
required
decimal
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": ["required", "maxlen:300"], "type": "string"}, "reference": {"description": "Business\u0027 reference of the payment order", "rules": ["maxlen:300"], "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": ["required", "maxlen:300"], "type": "string"}, "reference": {"description": "Business\u0027 reference of the payment order", "rules": ["maxlen:300"], "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
uuid uuid
UUID of the payment order

Validation Rules
required
expiration_time ISO_8601_date
Expiration's date of the payment order

Validation Rules
required
rate RateRetrieval
Crypto/Fiat rate of the payment order

Validation Rules
required
address string
Bitcoin address of the payment order

Validation Rules
regex :^
required
amount integer
Crypto amount of the payment order

Validation Rules
required
expires_in integer
Expiration's time of the payment order

Validation Rules
required
uri string
Bitcoin uri according to BIP 21 (https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki)

Validation Rules
regex :^
required
redirect_url url
URL where to redirect the user to perform the payment

Validation Rules
regex :https_url
required
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"}, "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"}, "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"}, "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"}, "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": []}

ClientCredentials

Data required to perform a confidential client login

PROPERTIES
scope string
Oauth2 scope of the client's authorization

Validation Rules
in :*
required
grant_type string
Oauth2 Authorization's grant type

Validation Rules
equals :client_credentials
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
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
expires_in integer
Token's expiration time

Validation Rules
required
scope string
Authorization's scope

Validation Rules
nullable
access_token string
User's access token

Validation Rules
required
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": []}

CallbackPaymentOrder

Payment order retrieval data

PROPERTIES
expiration_time ISO_8601_date
Expiration date of the payment order

Validation Rules
required
rate RateRetrieval
Crypto/Fiat rate of the payment order

Validation Rules
required
address base58
Bitcoin address of the payment order

Validation Rules
required
expires_in integer
Expiration time of the payment order

Validation Rules
required
uri string
Bitcoin uri

Validation Rules
required
created_by PaymentOrderCreator
Data of the pos which created the payment order

Validation Rules
required
state PaymentOrderState
Current payment state of the payment order

Validation Rules
required
continue_url url
The URL where the user is redirected upon successful payment

Validation Rules
regex :https_url
required
currency CurrencyRetrieval
Fiat currency of the payment order

Validation Rules
required
chargeback_date ISO_8601_date
Time at which either the payment order has been fully paid or is expired

Validation Rules
required
nullable
required_confirmations integer
Required confirmations for transactions paying the payment order

Validation Rules
required
reference string
Business' reference for the payment order

Validation Rules
nullable
required
resolved_at ISO_8601_date
Time at which either the payment order has been fully paid or is expired

Validation Rules
required
nullable
cancel_url url
The URL where the user is redirected upon payment order expiration/cancellation

Validation Rules
regex :https_url
required
redirect_url url
URL where to redirect the user to perform the payment

Validation Rules
regex :https_url
required
amount string
Fiat's amount of the payment order

Validation Rules
decimal
required
created_at ISO_8601_date
Creation date of the payment order

Validation Rules
required
uuid uuid
UUID of the payment order

Validation Rules
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
btc_amount integer
Bitcoin amount of the payment order

Validation Rules
required
details string
Payment order's details

Validation Rules
required
nullable
callback_url url
The URL contacted to send callbacks related to payment status changes

Validation Rules
regex :https_url
required
transactions array[Transaction]
Transactions paying the payment order

Validation Rules
nullable
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 is ctive", "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"], "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": ["required", "nullable"], "schema": {"crypto": {"description": "Cryto Amount", "rules": ["required"], "type": "integer"}, "fiat": {"description": "Fiat Amount", "rules": ["required", "decimal"], "type": "string"}}, "type": "object"}, "paid": {"rules": ["required", "nullable"], "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": ["required", "nullable"], "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", "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": ["required", "nullable"], "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