​

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.

​

Boxo Payments flow

Here is diagram showcasing the payment of miniapp’s order with the host app’s payment system

Here is the streamlined process for handling payment in a Boxo Miniapp:

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

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

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

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

5. Boxo Platform returns the orderPaymentID to the Miniapp server.

6. Miniapp server sends the orderPaymentID to the Miniapp.

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

8. 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 the payment on the payment confirmation page.

10. 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. The Miniapp handles the payment status event from the Boxo JS SDK and updates the order payment status in the Miniapp server.

12. 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. Finally, the Miniapp shows the order payment status page to the user.

​

Setting up the backend

Note: Feature must be enabled in Dashboard Partnership

Data 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.

​

1. “Create Order Payment” Request

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 enabled

Headers

Body:

Here is the data for OrderDetails, OrderItem, and OrderShippingAddress in a clean, well-structured format:

OrderDetails

OrderItem

OrderShippingAddress

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:

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."
    }

​

2. “Get Order Payment Status” Request

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 enabled

Headers:

Body:

Response:

• Response status will be

  400

  in case there is error_code

• Response body:

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."
    }

​

3. Webhook “Complete Order Payment” Endpoint

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 Dashboard

• We suggest to whitelist our IP addresses for this endpoint.

Headers:

app_id and secret_key will be provided in Dashboard

Body:

Response:

• Response status must be

  200

  in all cases

• Response body:

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"
    }

​

Setting up the SDK

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