Before you start

Do these steps one time. Every journey needs them.

1. Get access

Step	What to do	Guide
1	Get a sandbox API token	Authentication
2	Register a webhook URL, so Hubpay can send you events	Test payment webhooks
3	Find your AccountId	Hubpay gives it to you with your clientId and clientSecret during integration onboarding. It is not in the token response. See Get started

2. Use these headers

All journey requests use this base URL and these headers. Replace <YOUR_TOKEN> and <YOUR_ACCOUNT_ID> with your own values.

curl -X POST 'https://sandbox-api.hubpay.io/v1/collections/simulate-payment' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'AccountId: <YOUR_ACCOUNT_ID>' \
  -H 'Content-Type: application/json' \
  -d '{ ...request body from the scenario... }'

Every journey uses ORDER-10045 as the example payment request. Replace it with one of your own values:

You can send	Where you get it
Your own externalId	You chose it when you created the payment request
The Hubpay id (UUID)	The create payment request response
The paymentLinkReference, for example AH-LGWO-MGYL	The create response, and the payment URL

3. Crypto only

The crypto tabs use a real checkout quote. Do this for each journey:

1. Create a payment request with CRYPTO in paymentMethods and executionMode set to HOSTED_PAGE or EMBEDDED.
2. Open the paymentUrl from the response. Complete the payer steps and select a cryptocurrency and network, until checkout shows the deposit address.
3. No wallet: do not send tokens. The journey uses the simulator instead.
4. Test wallet: send Sepolia USDC from MetaMask as the journey describes.

Selecting the cryptocurrency creates the quote. The simulator uses that quote's token, network and rate. Keep these values from each simulator response:

Value	Used for
A new UUID you generate	depositId. One depositId is one transfer.
paymentId	Completing the payment
quotePaymentId	Optional. Selecting the same quote again later.

The simulator does not touch a blockchain. For the test wallet tabs, first follow Set up a test crypto wallet and ask Hubpay for sandbox USDC.

Words used in the journeys

Word	Meaning
Payment request	An invoice you create with the API. The payer pays it. Its status is UNPAID, PART_PAID, PAID, EXPIRED or CANCELLED.
Payment	One transfer from the payer. One payment request can have many payments. Its status is PENDING, RECEIVED, COMPLETE or FAILED.
Checkout	The Hubpay web page where the payer pays. executionMode chooses the type: PAYMENT_LINK, HOSTED_PAGE or EMBEDDED.
Expiry	HOSTED_PAGE and EMBEDDED requests stop accepting payment after a time limit. PAYMENT_LINK requests never expire.
Quote	Crypto only. The fixed crypto amount and exchange rate the payer sees for a short time.
Deposit	Crypto only. One crypto transfer from the payer.
Complete	The payment becomes COMPLETE and sends payment.completed. For bank transfer and crypto, Hubpay also credits the money to your wallet. In sandbox, a simulated card payment completes without adding to the wallet balance.
Simulate	Ask Hubpay to pretend something happened.

Webhook names in the journeys are short. payment.received means v1.collection.payment_request.payment.received. payment_request.paid means v1.collection.payment_request.paid. See the event catalogue for the full list.