Skip to main content

​
Introduction

Boxo Payments is an integrated in-app payment solution that enables users of host apps to securely make payments for orders directly within a miniapp. By leveraging the Boxo platform, it simplifies the payment process, allowing users to complete transactions seamlessly without leaving the host app environment. This functionality ensures a smooth and secure payment experience for users, while providing miniapp developers with an easy-to-integrate solution for handling payments within their services.
Here is diagram showcasing the payment of miniapp’s order with the host app’s payment systemPaymentsHere is the streamlined process for handling payment in a Boxo Miniapp:
1

User reaches payment page

User reaches the payment page in the Miniapp and proceeds to create an order.
2

Miniapp creates order request

Miniapp server creates the order and sends a createOrderPayment request to the Boxo Platform.
3

Platform initiates payment

Boxo Platform initiates the payment request on the Host app server.
4

Host app returns payment ID

Host app server returns the orderPaymentID to the Boxo Platform.
5

Platform forwards payment ID

Boxo Platform returns the orderPaymentID to the Miniapp server.
6

Miniapp receives payment ID

Miniapp server sends the orderPaymentID to the Miniapp.
7

SDK processes payment

The Miniapp passes the orderPaymentID to the Boxo JS SDK pay method.
8

Native SDK displays confirmation

The Boxo Native SDK listens for the pay event triggered by the Boxo JS SDK and displays the payment confirmation page to the user.
9

User confirms payment

User confirms the payment on the payment confirmation page.
10

Host app processes payment

The Host app handles the payment and sends the payment status back to the Boxo JS SDK pay event.
  • During payment processing, the Host app server sends a callback to the Boxo Platform to update the order in the Miniapp backend.
11

Miniapp handles payment status

The Miniapp handles the payment status event from the Boxo JS SDK and updates the order payment status in the Miniapp server.
12

Payment status confirmation

Miniapp confirms the order payment status.
  • If the order is still processing, the Miniapp will request the payment status from the Boxo Platform, which in turn will request the payment status from the Host app server.
13

Display payment result

Finally, the Miniapp shows the order payment status page to the user.
Note: Feature must be enabled in Dashboard PartnershipPaymentEnabledData format Currently, the Boxo platform uses JSON format for data exchange. When working with decimals, they are represented as either float, number, or string, with a maximum of 20 digits and 2 digits after the decimal point. Additionally, the data type definitions include limits on the size of strings, ensuring consistent and manageable data structures across systems.
This endpoint is on Boxo platform. Send request to create order payment (see step 2 in diagram).URL and METHOD:This is HTTPS POST /api/v1/orders/create-order-payment/ endpoint IP address of requesting services must be provided in Dashboard for whitelisting or Request Signaturing must be enabledHeaders
KeyValue
Content-typeapplication/json
Body:
FieldData typeOptionalDescription
app_idStringNoMiniapp identifier
client_idStringNoHostapp identifier
orderOrderDetailsNoOrder info (amount, currency and etc.)
Here is the data for OrderDetails, OrderItem, and OrderShippingAddress in a clean, well-structured format:OrderDetails
FieldData TypeOptionalDescription
currencyString(20)NoOrder amount currency
amountDecimalNoOrder amount
subtotal_amountDecimalYesSubtotal amount of the order
shipping_amountDecimalYesShipping cost
discount_amountDecimalYesDiscount applied on the order
tax_titleString(250)YesTitle of the tax applied
tax_amountDecimalYesTax amount
taxes_includedBoolYesIndicates whether taxes are included
noteStringYesAdditional notes for the order
miniapp_order_idString(250)YesOrder reference in the miniapp
hostapp_user_idString(250)YesUser reference in the host app
itemsOrderItem[]YesList of items purchased in the order
shipping_addressOrderShippingAddressYesShipping address information
custom_attributesJSONYesCustom attributes for the order
OrderItem
FieldData TypeOptionalDescription
product_nameString(250)YesName of the product
product_variant_nameString(250)YesName of the product variant
product_skuString(250)YesProduct SKU
product_image_urlString(250)YesURL of the product image
quantityIntegerYesQuantity of the product in the order
priceDecimalYesPrice of the product
discountDecimalYesDiscount applied to the product
OrderShippingAddress
FieldData TypeOptionalDescription
address1String(1000)YesAddress line 1
address2String(1000)YesAddress line 2
first_nameString(250)YesFirst name of the recipient
last_nameString(250)YesLast name of the recipient
phoneString(250)YesPhone number of the recipient
region_nameString(100)YesName of the region or state
region_codeString(100)YesCode of the region or state
province_nameString(250)YesName of the province
province_codeString(250)YesCode of the province
cityString(250)YesCity of the recipient
countryString(250)YesCountry of the recipient
postal_codeString(250)YesPostal code of the recipient
latitudeDecimalYesLatitude of the shipping address (up to 15 digits after the decimal)
longitudeDecimalYesLongitude of the shipping address (up to 15 digits after the decimal)
Decimal Limits for Coordinates:
  • Latitude: Max value: 90, Min value: -90, max 17 digits with 15 digits after the decimal point.
  • Longitude: Max value: 180, Min value: -180, max 18 digits with 15 digits after the decimal point.
Response:
  • Response status will be 400 in case there is error_code
  • Response body:
FieldData typeOptionalDescription
order_payment_idString(250)YesOrder payment identifier
error_codeStringYesIf some error is occured error code should be provided. Example: {"error_code": "INVALID_ORDER_DATA"} All error codes can be found here
Request Example:
    curl --location --request POST '[BOXO_PLATFORM_SERVER_URL]/api/v1/orders/create-order-payment/'\
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic {{BASE64_ENCODED_CLIENT_ID_AND_CLIENT_SECRET}}' \
    --data-raw '{
        "app_id": "{{MINIAPP_ID}}",
        "client_id": "{{CLIENT_ID}}",
        "order": {
            "amount": "100.00",
            "currency": "USD",
            "miniapp_order_id": "{{ MINIAPP_ORDER_ID }}",
            "hostapp_user_id": "{{ HOSTAPP_USER_ID }}"
        }
    }'
Response Example:
    {
        "order_payment_id": "8X566iHGnpUxHXPX3FH0iDsXUVn9ku16xJGQ"
    }

    {
        "error_code": "UNKNOWN_ERROR",
        "error_message": "Unknown error. Please try again later."
    }
This endpoint is on Boxo platform. Send request to get order payment status (see “Check order status” step in diagram).URL and METHOD: This is HTTPS POST /api/v1/orders/get-payment-status/ endpoint IP address of requesting services must be provided in Dashboard for whitelisting or Request Signaturing must be enabledHeaders:
KeyValue
Content-typeapplication/json
Body:
FieldData typeOptionalDescription
app_idStringNoMiniapp identifier
client_idStringNoHostapp identifier
order_payment_idString(250)NoOrder payment identifier
Response:
  • Response status will be 400 in case there is error_code
  • Response body:
FieldData typeDescription
order_payment_idStringOrder payment identifier
app_idStringMiniapp identifier
client_idStringHostapp identifier
payment_statusStringOrder payment status: in_process| paid| cancelled |failed
payment_fail_reasonStringOrder payment fail reason
error_codeStringError code. Example: {"error_code": "ORDER_NOT_FOUND"} All error codes can be found here
Request Example
    curl --location --request POST '[BOXO_PLATFORM_SERVER_URL]/api/v1/orders/get-payment-status/'\
    --header 'Content-Type: application/json' \
    --data-raw '{
        "app_id": "{{MINIAPP_ID}}",
        "client_id": "{{CLIENT_ID}}",
        "order_payment_id": "{{ORDER_PAYMENT_ID}}"
    }'

    {
        "order_payment_id": "{{ORDER_PAYMENT_ID}}",
        "app_id": "{{MINIAPP_ID}}",
        "client_id": "{{CLIENT_ID}}",
        "payment_status": "failed",
        "payment_fail_reason": "Payment amount exceeds user's amount limit."
    }

    {
        "error_code": "ORDER_NOT_FOUND",
        "error_message": "No Order matches the given query."
    }
Setup this endpoint for Boxo platform to complete order payment(see step after 10 in diagram).URL and METHOD: This endpoint must handle a HTTPS POST request URL to endpoint must be provided in DashboardPayments_miniApp
  • We suggest to whitelist our IP addresses for this endpoint.
Headers:
KeyValue
AuthorizationBasic <base64 encoded(app_id:secret_key)>
Content-typeapplication/json
app_id and secret_key will be provided in DashboardBody:
FieldData typeDescription
miniapp_order_idString(250)Miniapp order indentifier
hostapp_order_payment_idString(250)Order payment identifier
hostapp_client_idString(250)Hostapp identifier
payment_statusStringOrder payment status: in_process| paid| cancelled| failed
payment_fail_reasonStringOrder payment fail reason
custom_attributesJSONOrder custom attributes
Response:
  • Response status must be 200 in all cases
  • Response body:
FieldData typeDescription
codeStringRequest result code example: SUCCESS
error_codeStringError code
Request Example:
    curl --location --request POST '[YOUR_SERVER_URL]/api/complete-order/' \
    --header 'Authorization: Basic {{BASE64_ENCODED_APP_ID_AND_SECRET_KEY}}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "miniapp_order_id": "{{MINIAPP_ORDER_ID}}",
        "hostapp_client_id": "{{CLIENT_ID}}",
        "hostapp_order_payment_id": "{{ORDER_PAYMENT_ID}}",
        "payment_status": "paid"
    }'
Response Example:
    {
        "code": "SUCCESS"
    }

    {
        "error_code": "ORDER_NOT_FOUND"
    }
When the order is created payment should be handled on host app’s side. Use appboxoSdk.pay method as in example to open payment pages on host app.
const payResponse = await appboxoSdk.pay({
    amount,
    currency,
    miniappOrderId, // order reference
    transactionToken, // pass order_payment_id 
    extraParams: {},
})
const { status } = payResponse