> For the complete documentation index, see [llms.txt](https://developers.unigox.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.unigox.com/tutorials/on-ramp-playbook.md).

# On Ramp Playbook

## On Ramp Playbook

The full phased on-ramp integration flow — from one-time setup to operational monitoring.

### Phase 1: Initial configuration

One-time setup before going live.

| Step | Action                                                | Endpoint                           |
| ---- | ----------------------------------------------------- | ---------------------------------- |
| 1    | Obtain your X-API-Key and webhook\_secret from Unigox | —                                  |
| 2    | Register your webhook endpoint                        | POST /api/v1/partner/webhooks      |
| 3    | Validate webhook delivery                             | POST /api/v1/partner/webhooks/test |

### Phase 2: Per-user onboarding

Required once per end-user before they can transact.

| Step | Action                    | Endpoint                                  |
| ---- | ------------------------- | ----------------------------------------- |
| 1    | Create the user           | POST /api/v1/partner/users                |
| 2    | Submit KYC data           | POST /api/v1/partner/users/{id}/kyc       |
| 3    | Upload identity documents | POST /api/v1/partner/users/{id}/documents |
| 4    | Check verification status | GET /api/v1/partner/users/{id}            |

### Phase 3: On-ramp transaction lifecycle

| Step | Action                                                        | Endpoint                                                               |
| ---- | ------------------------------------------------------------- | ---------------------------------------------------------------------- |
| 1    | (Optional) Get price estimate                                 | POST /api/v1/partner/onramp/estimate                                   |
| 2    | Get quote                                                     | POST /api/v1/partner/onramp/quote                                      |
| 3    | Initiate order                                                | POST /api/v1/partner/onramp/initiate                                   |
| 4    | Webhook: awaiting\_vendor\_escrow\_funding                    | —                                                                      |
| 5    | Webhook: awaiting\_fiat\_transfer                             | —                                                                      |
| 6    | Get vendor payment details, forward to end-user               | GET /api/v1/partner/orders/{order\_id}                                 |
| 7    | (payment\_request only) Submit payer details                  | POST /api/v1/partner/orders/{order\_id}/submit-payer-details           |
| 8    | Confirm payment sent                                          | POST /api/v1/partner/orders/{order\_id}/confirm-payment-sent           |
| 9    | Webhook: fiat\_transfer\_pending                              | —                                                                      |
| 10   | Webhook: completed                                            | —                                                                      |
| 11   | (Optional) Get send-out parameters                            | GET /api/v1/partner/orders/{order\_id}/bridge-authorization-parameters |
| 12   | (Optional) Authorize send-out                                 | POST /api/v1/partner/orders/{order\_id}/authorize-bridge               |
| 13   | (Optional) Webhook: send\_out\_pending → send\_out\_completed | —                                                                      |

Terminal states: completed, cancelled, failed, dispute\_started

### Phase 4: Ongoing operations

Webhooks should remain the primary source of truth. Use polling only for recovery or reconciliation.

| Action                 | Endpoint                               |
| ---------------------- | -------------------------------------- |
| Check individual order | GET /api/v1/partner/orders/{order\_id} |
| List all orders        | GET /api/v1/partner/orders             |