Boxo Payments is an in-app payment functionality that enables host app users to complete payments for orders within the miniapp.
Here is a diagram illustrating the payment process for a miniapp order using the host app’s payment system.
pay
method.*Note: Feature must be enabled in Dashboard Partnership
Data format
Currently, JSON is used for data exchange. Decimal values can be represented as floats, numbers, or strings, with a maximum of 20 digits in total and up to 2 digits after the decimal point. String size limits are defined within the data type specifications.
This endpoint allows the Boxo Platform to create an order payment (refer to Step 3 in the diagram).
URL and METHOD:
This endpoint must handle a HTTPS POST request URL to endpoint must be provided in Dashboard
Headers:
Key | Value |
---|---|
Authorization | <prefix> <base64 encoded(hostapp_client_id:hostapp_secret_key)> |
Content-type | application/json |
<prefix>
: Token
. Access token prefix can be set in Boxo Connect.Use access token
in Dashboard.hostapp_client_id
and hostapp_secret_key
must be provided in DashboardBody
Field | Data type | Description |
---|---|---|
app_id | String | Miniapp identifier |
order | OrderDetails | Order info (amount, currency and etc.) |
OrderDetails:
Field | Data type | Optional | Description |
---|---|---|---|
product_name | String(250) | Yes | Product name |
product_variant_name | String(250) | Yes | Product variant name |
product_sku | String(250) | Yes | Product SKU |
product_image_url | String(250) | Yes | Product image url |
quantity | Integer | Yes | |
price | Decimal | Yes | |
discount | Decimal | Yes | Discount applied on a product |
OrderShippingAddress:
Field | Data type | Optional | Description |
---|---|---|---|
address1 | String(1000) | Yes | |
address2 | String(1000) | Yes | |
first_name | String(250) | Yes | |
last_name | String(250) | Yes | |
phone | String(250) | Yes | |
region_name | String(100) | Yes | |
region_code | String(100) | Yes | |
province_name | String(250) | Yes | |
province_code | String(250) | Yes | |
city | String(250) | Yes | |
country | String(250) | Yes | |
postal_code | String(250) | Yes | |
latitude | Decimal | Yes | Decimal limits: max 17 digits, 15 digits after decimal point. Max value: 90, Min value: -90 |
longitude | Decimal | Yes | Decimal limits: max 18 digits, 15 digits after decimal point. Max value: 180, Min value: -180 |
Response:
200
in all casesField | Data type | Optional | Description |
---|---|---|---|
order_payment_id | String(250) | Yes | Order payment identifier |
error_code | String | Yes | If some error is occured error code should be provided. Example: {"error_code": "INVALID_ORDER_DATA"} All error codes can be found here |
Request Example:
This endpoint is for Boxo platform to get order payment status
URL and METHOD
This endpoint must handle a HTTPS POST request URL to endpoint must be provided in Dashboard
Headers
Key | Value |
---|---|
Authorization | <prefix> <base64 encoded(hostapp_client_id:hostapp_secret_key)> |
Content-type | application/json |
Default <prefix>
: Token. Access token prefix can be set in Boxo Connect.
To use user access token from Boxo Connect as authorization token enable Use access token
in Dashboard.
hostapp_client_id
and hostapp_secret_key
must be provided in Dashboard
Body
Field | Data type | Description |
---|---|---|
app_id | String | Miniapp identifier |
client_id | String | Hostapp identifier |
order_payment_id | String | Order payment identifier |
Response
200
in all casesField | Data type | Optional | Description |
---|---|---|---|
app_id | String | Yes, in case error_code passed | Miniapp identifier |
client_id | String | Yes, in case error_code passed | Hostapp identifier |
order_payment_id | String | Yes, in case error_code passed | Order payment identifier |
payment_status | String(100) | Yes, in case error_code passed | Order payment status: in_process , paid , cancelled , failed |
payment_fail_reason | String | Yes | Order payment fail reason |
error_code | String | Yes | If some error is occured error code should be provided. Example: {"error_code": "ORDER_NOT_FOUND"} All error codes can be found here |
Request Example
This endpoint is part of the Boxo Platform. It sends a request to the miniapp server to complete the order payment after the payment has been processed (refer to the step after 10 in the diagram).
URL and METHOD
This is HTTPS POST /api/v1/orders/complete-order/
endpoint
IP address of requesting services must be provided in Dashboard for whitelisting or Request Signaturing must be enabled
Headers
Key | Value |
---|---|
Content-type | application/json |
Body
Field | Data type | Optional | Description |
---|---|---|---|
order_payment_id | String(250) | Yes, in case error_code passed | Order payment identifier |
app_id | String | Yes, in case error_code passed | Miniapp identifier |
client_id | String | Yes, in case error_code passed | Hostapp identifier |
payment_status | String(100) | Yes, in case error_code passed | Order payment status: in_process , paid , cancelled , failed |
payment_fail_reason | String | Yes | Order payment fail reason |
error_code | String | Yes | If some error is occured error code should be provided. Example: {"error_code": "ORDER_NOT_FOUND"} All error codes can be found here |
Response:
400
in case there is error_codeField | Data type | Description |
---|---|---|
code | String | Request result code example: SUCCESS |
message | String | Result message |
error_code | String | Error code |
error_message | String | Result error message. All error codes can be found here |
Request Example
Response Example
Listening for Payment event
Kotlin
Important
To show payment processing on Flutter, need to enable ‘multitaskMode’. Miniapp opens on a native screen. To show payment processing need to hide miniapp screen.
Boxo.setConfig('[CLIENT_ID]', multitaskMode: true);
Important
To show payment processing on React Native, need to enable ‘multitaskMode’. Miniapp opens on a native screen. To show payment processing need to hide miniapp screen.
Boxo.setConfig('[CLIENT_ID]', { enableMultitaskMode: true })
Boxo Payments is an in-app payment functionality that enables host app users to complete payments for orders within the miniapp.
Here is a diagram illustrating the payment process for a miniapp order using the host app’s payment system.
pay
method.*Note: Feature must be enabled in Dashboard Partnership
Data format
Currently, JSON is used for data exchange. Decimal values can be represented as floats, numbers, or strings, with a maximum of 20 digits in total and up to 2 digits after the decimal point. String size limits are defined within the data type specifications.
This endpoint allows the Boxo Platform to create an order payment (refer to Step 3 in the diagram).
URL and METHOD:
This endpoint must handle a HTTPS POST request URL to endpoint must be provided in Dashboard
Headers:
Key | Value |
---|---|
Authorization | <prefix> <base64 encoded(hostapp_client_id:hostapp_secret_key)> |
Content-type | application/json |
<prefix>
: Token
. Access token prefix can be set in Boxo Connect.Use access token
in Dashboard.hostapp_client_id
and hostapp_secret_key
must be provided in DashboardBody
Field | Data type | Description |
---|---|---|
app_id | String | Miniapp identifier |
order | OrderDetails | Order info (amount, currency and etc.) |
OrderDetails:
Field | Data type | Optional | Description |
---|---|---|---|
product_name | String(250) | Yes | Product name |
product_variant_name | String(250) | Yes | Product variant name |
product_sku | String(250) | Yes | Product SKU |
product_image_url | String(250) | Yes | Product image url |
quantity | Integer | Yes | |
price | Decimal | Yes | |
discount | Decimal | Yes | Discount applied on a product |
OrderShippingAddress:
Field | Data type | Optional | Description |
---|---|---|---|
address1 | String(1000) | Yes | |
address2 | String(1000) | Yes | |
first_name | String(250) | Yes | |
last_name | String(250) | Yes | |
phone | String(250) | Yes | |
region_name | String(100) | Yes | |
region_code | String(100) | Yes | |
province_name | String(250) | Yes | |
province_code | String(250) | Yes | |
city | String(250) | Yes | |
country | String(250) | Yes | |
postal_code | String(250) | Yes | |
latitude | Decimal | Yes | Decimal limits: max 17 digits, 15 digits after decimal point. Max value: 90, Min value: -90 |
longitude | Decimal | Yes | Decimal limits: max 18 digits, 15 digits after decimal point. Max value: 180, Min value: -180 |
Response:
200
in all casesField | Data type | Optional | Description |
---|---|---|---|
order_payment_id | String(250) | Yes | Order payment identifier |
error_code | String | Yes | If some error is occured error code should be provided. Example: {"error_code": "INVALID_ORDER_DATA"} All error codes can be found here |
Request Example:
This endpoint is for Boxo platform to get order payment status
URL and METHOD
This endpoint must handle a HTTPS POST request URL to endpoint must be provided in Dashboard
Headers
Key | Value |
---|---|
Authorization | <prefix> <base64 encoded(hostapp_client_id:hostapp_secret_key)> |
Content-type | application/json |
Default <prefix>
: Token. Access token prefix can be set in Boxo Connect.
To use user access token from Boxo Connect as authorization token enable Use access token
in Dashboard.
hostapp_client_id
and hostapp_secret_key
must be provided in Dashboard
Body
Field | Data type | Description |
---|---|---|
app_id | String | Miniapp identifier |
client_id | String | Hostapp identifier |
order_payment_id | String | Order payment identifier |
Response
200
in all casesField | Data type | Optional | Description |
---|---|---|---|
app_id | String | Yes, in case error_code passed | Miniapp identifier |
client_id | String | Yes, in case error_code passed | Hostapp identifier |
order_payment_id | String | Yes, in case error_code passed | Order payment identifier |
payment_status | String(100) | Yes, in case error_code passed | Order payment status: in_process , paid , cancelled , failed |
payment_fail_reason | String | Yes | Order payment fail reason |
error_code | String | Yes | If some error is occured error code should be provided. Example: {"error_code": "ORDER_NOT_FOUND"} All error codes can be found here |
Request Example
This endpoint is part of the Boxo Platform. It sends a request to the miniapp server to complete the order payment after the payment has been processed (refer to the step after 10 in the diagram).
URL and METHOD
This is HTTPS POST /api/v1/orders/complete-order/
endpoint
IP address of requesting services must be provided in Dashboard for whitelisting or Request Signaturing must be enabled
Headers
Key | Value |
---|---|
Content-type | application/json |
Body
Field | Data type | Optional | Description |
---|---|---|---|
order_payment_id | String(250) | Yes, in case error_code passed | Order payment identifier |
app_id | String | Yes, in case error_code passed | Miniapp identifier |
client_id | String | Yes, in case error_code passed | Hostapp identifier |
payment_status | String(100) | Yes, in case error_code passed | Order payment status: in_process , paid , cancelled , failed |
payment_fail_reason | String | Yes | Order payment fail reason |
error_code | String | Yes | If some error is occured error code should be provided. Example: {"error_code": "ORDER_NOT_FOUND"} All error codes can be found here |
Response:
400
in case there is error_codeField | Data type | Description |
---|---|---|
code | String | Request result code example: SUCCESS |
message | String | Result message |
error_code | String | Error code |
error_message | String | Result error message. All error codes can be found here |
Request Example
Response Example
Listening for Payment event
Kotlin
Important
To show payment processing on Flutter, need to enable ‘multitaskMode’. Miniapp opens on a native screen. To show payment processing need to hide miniapp screen.
Boxo.setConfig('[CLIENT_ID]', multitaskMode: true);
Important
To show payment processing on React Native, need to enable ‘multitaskMode’. Miniapp opens on a native screen. To show payment processing need to hide miniapp screen.
Boxo.setConfig('[CLIENT_ID]', { enableMultitaskMode: true })