Authentication

Before you begin

Credentials. Contact Ripio support to request your partner registration and obtain the client_id and client_secret that univocally identify you as a Ripio customer. It is your responsibility to secure them.
A redirect URL. Ripio needs a publicly reachable URL to send the user back to once the operation is confirmed. You give it to Ripio during onboarding and it is configured on your account — see Returning to your app.
Whether your account requires a wallet address. If it does, the username below must carry a third segment. See Errors.

This is the only widget endpoint you call. Every other request — quotes, orders, verification, history, refunds — is made by the widget itself on the user’s behalf, so there is no other widget API for you to integrate against. What your backend observes instead are the Ramps webhooks you already receive.

Generate authentication token

This service provides an access JWT token for the user to use the On Ramp Widget. Endpoint: https://b2b-widget-onramp-api.ripio.com/api/v1/auth

Sandbox:: https://b2b-widget-onramp-api.sandbox.ripio.com/api/v1/auth

Method: POST Parameters:

Parameter	Type	Description
`username`	string	The username is composed of a concatenation of `client_id` + “`:`” + `external_ref` + “`:`” + `address`.
`password`	string	The password is the `client_secret`

Disclaimer:

external_ref: UUID v4 that represents the user logged into your system. It must be a unique and unrepeatable identifier of a user of your system (Read more about UUID and try using generator). This value is then used in the request for approval of a purchase transaction or when reporting the result of a transaction. (see Webhooks). In the documentation we refer to this value as external_ref. It is validated as a UUID, so a non-UUID value is rejected.
address: A string that represents the blockchain address or wallet identifier for the user. For off-ramp operations, use the same address as used in on-ramp. Whether it is mandatory depends on your partner configuration — if your account requires it, omitting it returns a 422 (see Errors). If it is not required for your account, you can send a two-part username (client_id:external_ref).

Request:

curl \
--location --request POST 'https://b2b-widget-onramp-api.ripio.com/api/v1/auth' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=<client_id>:<external_ref>:<address>' \
--data-urlencode 'password=<client_secret>'

Example:

curl \
--location --request POST 'https://b2b-widget-onramp-api.ripio.com/api/v1/auth' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=<client_id>:123e4567-e89b-42d3-a456-426614174000:0x05946b0d5E413e45069BeC923004F9A3c8F70C2C' \
--data-urlencode 'password=<client_secret>'

Response:

{
    "succeed": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uIjoiMThhYjZkNmM4ZDk4NWE5Y2M4N2IwMTcyN2ExMWYwOTQ4YzJmNGUxYzQ0ODEzZTZhNDU0MzcxYTg1NzY3YjE5OSIsImV4cCI6MTcwODI5ODMzM30.4aRUEXLkUs3jf-DYMcH8claUuDKfc8qbTjW6JzpBTjI",
    "token_type": "bearer"
}

This endpoint returns the token under a token key, not nested under data like most other widget API responses.

Errors

Validation failures return HTTP 422 with a flat body — just a detail string field:

{
    "detail": "address is required for this partner"
}

`detail`	Cause
`address is required for this partner`	Your account requires the wallet address and the `username` had no third segment. Note an explicitly empty third part (`client_id:external_ref:`) counts as missing.
`username must be in format client_id:external_ref or client_id:external_ref:address`	The `username` had fewer than 2 or more than 3 colon-separated segments.
`missing external_ref`	The second segment of the `username` was empty.
`The external_ref is not a UUID`	The `external_ref` was present but not a valid UUID.

Overview

Widget integration

API Integration

Before you begin

Generate authentication token

Errors

​Before you begin

​Generate authentication token

​Errors

Before you begin

Generate authentication token

Errors