MobiSend CashApp Checkout API¶

End-user CashApp payment rails for MobiSend's iOS / web app. End-users pay via CashApp (hosted Pockyt page); we execute the topup automatically once payment confirms.

Production base URL: https://app.via.one/api/mobisend

Architecture overview¶

MobiSend app                   Via.One API              Pockyt              End-user
     │                              │                      │                    │
     │  POST /cashapp/checkout      │                      │                    │
     ├─────────────────────────────►│                      │                    │
     │                              │ pockyt.createPayment │                    │
     │                              ├─────────────────────►│                    │
     │                              │ ◄─────── cashier_url │                    │
     │ ◄────── payment_url + ref    │                      │                    │
     │                              │                      │                    │
     │  Show payment_url to user    │                      │                    │
     │═════════════════════════════════════════════════════════════════════════►│
     │                              │                      │ ◄── pays via CashApp
     │                              │                      │                    │
     │                              │ ◄── IPN webhook ─────┤                    │
     │                              │   payment confirmed  │                    │
     │                              │                      │                    │
     │                              │  fulfillOrder() →                          │
     │                              │    routes by carrier                       │
     │                              │    executes topup                          │
     │                              │                      │                    │
     │ ◄── POST callback_url ───────┤                                            │
     │   {status: "completed"}     │                                            │

We are Merchant of Record via Pockyt store 305155 / Relier Group LLC.

Authentication¶

All endpoints require x-api-key header with your MobiSend API key (same key used for /topup, /billpay, /balance, etc.).

POST /cashapp/checkout¶

Create a Pockyt CashApp payment link. Returns a hosted URL to display to the end-user.

Request¶

POST /api/mobisend/cashapp/checkout
x-api-key: <your_mobisend_api_key>
Content-Type: application/json

{
  "phone": "5551234567",
  "amount": 20.00,
  "carrier": "att",
  "country": "US",
  "sku": "ATT20",
  "type": "topup",
  "reference": "MOBI-INTERNAL-12345",
  "callback_url": "https://your-domain.com/webhooks/viaone",
  "fee_mode": "passthrough"
}

Field reference¶

Field	Type	Required	Notes
`phone`	string	yes	End-user phone number, digits only
`amount`	number	yes	Topup amount the end-user will receive (USD)
`carrier`	string	yes	Carrier code: `att`, `tmobile`, `verizon`, `metropcs`, `cricket`, `boost`, `simplemobile`, `ultra`, `lyca`, `net10` (US); `telcel`, `movistar`, `att-mx`, `unefon`, `virgin` (MX)
`country`	string	no	ISO-2 country code. Default `US`.
`sku`	string	no	Specific product SKU if your catalog provides it
`type`	string	no	`topup` (default) or future expansion
`reference`	string	no	Your distributor-side transaction ID (echoed back in webhook)
`callback_url`	string	no	HTTPS URL we POST status updates to. If omitted, you must poll `GET /order/:order_id`.
`fee_mode`	string	no	`passthrough` (default — end-user pays $1 CashApp fee on top) or `absorb` (you eat the $1 fee from your margin)

Response (success)¶

{
  "success": true,
  "order_id": "8e1c2a3d-...-uuid",
  "order_reference": "ORD-1714510123-abc12",
  "payment_url": "https://m.pockyt.io/checkout/...",
  "amount_topup_usd": 20.00,
  "amount_charged_usd": 21.00,
  "fee_breakdown": {
    "cashapp_fee_usd": 1.00,
    "fee_mode": "passthrough"
  },
  "expires_at": "2026-04-30T19:00:00.000Z",
  "status": "pending_payment",
  "next_step": "Show payment_url to end-user. We will POST status to callback_url when Pockyt confirms payment and topup completes."
}

Response (validation error)¶

{
  "success": false,
  "error": "phone, amount, and carrier are required",
  "required_fields": { ... }
}

Response (Pockyt error)¶

{
  "success": false,
  "error": "Failed to create CashApp payment",
  "detail": "Pockyt error message",
  "order_reference": "ORD-..."
}

What MobiSend does next¶

Display payment_url to your end-user (in-app browser, deep link, or QR code).
End-user pays via CashApp on Pockyt's hosted checkout.
Wait for the callback (or poll GET /order/{order_id}).

Webhook payload (POST to your `callback_url`)¶

When the topup completes (success or permanent failure), we POST:

{
  "order_reference": "ORD-1714510123-abc12",
  "order_id": "8e1c2a3d-...-uuid",
  "status": "completed",
  "api_customer_id": "MOBISEND_001",
  "distributor_reference": "MOBI-INTERNAL-12345",
  "phone": "5551234567",
  "carrier": "att",
  "amount_topup_usd": 20.00,
  "amount_charged_usd": 21.00,
  "provider": "CELLPAY",
  "provider_transaction_id": "...",
  "auth_code": "12345",
  "response_code": "00",
  "response_message": "Approved",
  "completed_at": "2026-04-30T19:02:13.456Z"
}

Status values: - completed — topup landed on the end-user's phone - permanent_failure — topup will not retry (invalid number, unknown carrier, SKU not provisioned, etc.); CashApp payment may be refunded separately - (For transient failures we retry internally and only notify on final outcome)

Webhook timeout: we wait 10s for your endpoint to return any 2xx. We don't retry the callback — it's fire-and-forget. Use the polling endpoint as your source of truth.

GET /order/{order_id}¶

Polling endpoint — already documented in main MobiSend API. Returns the same status fields as the webhook.

Behavior details¶

Idempotency¶

Same idempotency-key header pattern as /topup. A repeated request with the same reference returns the original response.

Expiration¶

Checkout URL valid for 30 minutes. After expiry, status moves to expired and CashApp payment (if still in flight) won't trigger a topup.

Refunds¶

If we receive payment but fulfillment permanently fails: 1. We mark the order permanent_failure and POST your callback 2. You decide whether to refund the end-user via your CashApp business account (Pockyt has refund APIs but currently you'd handle on your end — happy to wire that in if you want)

Phone validation¶

We validate phone length per country: | Country | Expected digits | |---|---| | US | 10 | | MX | 10 | | HN, NI, SV, GT, CR, PA | 8 | | PH, CO, AR, VE | 10 | | PE, CL | 9 | | BR | 11 |

Amount caps¶

US: $500 USD max per transaction
MX: 5,000 MXN max
Daily limit: $10,000 USD across all of MobiSend's transactions

Fees you pay¶

Pockyt CashApp: $1 USD per successful payment (passed through by default)
Per-topup margin: per your existing MobiSend commercial agreement with us (separate from CashApp fee)

Quick test (curl)¶

# 1. Create a checkout
curl -X POST https://app.via.one/api/mobisend/cashapp/checkout \
  -H "x-api-key: $MOBISEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5551234567",
    "amount": 5.00,
    "carrier": "att",
    "country": "US",
    "reference": "TEST-001",
    "callback_url": "https://webhook.site/your-test-url"
  }'

# 2. Open the returned payment_url in a browser to simulate end-user

# 3. Pay via CashApp on Pockyt's hosted page

# 4. Receive callback at the URL above (or poll GET /order/{order_id})

Support¶

Issues, integration questions, custom flows: ping Richard directly. Webhook signature verification is on Pockyt's side; if you want signed callbacks from us to you (HMAC), let us know — easy to add.