Accept stablecoin pay-ins with real-time settlement. Issue on-chain refunds.
This guides walks you through the steps to set up a basic payments workflow using the Paxos Platform, including configuring a stablecoin pay-in workflow and setting up a refund workflow.
Once completed, similar, more robust, workflows can be implemented in production.
If you already have sandbox access, this guide should take less than one hour to complete.
Confirm the response includes the requisite scopes and save the access_token to use in the request authorization header (-H "Authorization: Bearer access_token").
Use List Profiles to retrieve the Profile ID when needed.
To represent the Buyer in this guide, send enough testnet tokens to pay network fees, along with one of the supported testnet stablecoins, to an off-platform wallet.
To accept a pay-in on the Paxos Platform, first use Create Deposit Address to add a new wallet address on the public blockchain.
Then add the deposit address as a stablecoin payment option for Buyers, typically at checkout.
Using a wallet connector or displaying a QR code in the Buyer interface helps to ensure that Buyers send the correct amount and avoid errors.
Once a Buyer completes a purchase, the transaction shows up in the List Transfers monitoring and reconciliation polling request.
Use Create Deposit Address to add a wallet address to the Profile designated for the Seller.
The request must include one of supported stablecoins networks.
Set conversion_target_asset to USD to automatically convert stablecoin pay-ins to USD on the Paxos Platform.
Best PracticeWhenever possible, include your own unique identifier in the request using ref_id.
Doing so helps to protect against submitting the same request twice, as the second request with the same ref_id will be rejected with 409 already exists.
The ref_id can also be used in many query parameters.
The example uses SOLANA as the crypto_network.
If needed, use either ETHEREUM or POLYGON_POS for crypto_network.
Since the designated Profile has not gone through the Identity onboarding process, the default identity_id and account_id values appear in the response.
Onboarding Questions?
See the onboarding FAQ for details about user Identity and Account requirements.
Contact Support to help determine the best onboarding approach.
Off the Paxos Platform, share the deposit address with Buyers, typically on the checkout page, and start accepting stablecoin pay-ins.
Once a Buyer completes a pay-in transaction, Paxos credits the designated Profile with either stablecoin or USD, based on the deposit address configuration.
For this guide, all received pay-ins are automatically converted to USD on the Paxos Platform because we used “conversion_target_asset”: “USD”` when creating the deposit address.
3. Add Pay-in Monitoring and Reconciliation Request
Using List Transfers, create a recurring request that looks for completed transactions in the Seller’s Profile.
Retrieve the status for payments received in the deposit address using the profile_id, filtered by on the CRYPTO_DEPOSIT type and updated_at.gte parameters.
Best PracticeWe recommend to poll List Transfers globally at a set cadence (for example, at 1 second intervals), using slightly behind the last processed updated_at.gte as a synchronization checkpoint.
To manage on-platform cash balances, use the Fiat Transfers APIs to batch withdraw USD to any designated bank account as needed.
Learn more in the fiat transfers guide.
If you need to create a fiat account Paxos may need to enable some API functionality.
C> ontact Support for assistance.
To process stablecoin refunds on the Paxos Platform, first fund your account with USD then use Create Crypto Withdrawal to initiate a stablecoin refund to the Buyer.
Once a refund is complete, the transaction shows up in the List Transfers monitoring and reconciliation polling request.
Production implementations can use the Fiat Transfers APIs to send USD to a destination on the Paxos Platform, which is out of scope for this guide.
The fiat transfers guide provides step-by-step instructions on setting up fiat movements.
If you need to create a fiat account Paxos may need to enable some API functionality.
Contact Support for assistance.
For simplicity, this guide uses Create Sandbox Deposit to simulate funding the designated Seller Profile with USD.
Include the Seller’s Profile ID (profile_id) as a path parameter, as well as the deposit asset and amount as query parameters.
Set balance_asset to USD to automatically convert fiat to stablecoin and issue a refund in a single request.
For this guide, the refund is issued to the Buyer’s original wallet address (destination_address) using the same /guides/stablecoin/network pair:
The asset is PYUSD, the balance_asset is USD, and the crypto_network is SOLANA.
The funding source is the Seller’s Profile (profile_id) used earlier.
Best PracticeWhenever possible, include your own unique identifier in the request using ref_id.
Doing so helps to protect against submitting the same request twice, as the second request with the same ref_id will be rejected with 409 already exists.
The ref_id can also be used in many query parameters.
The initial response has a status of PENDING, since the on-chain transaction has not yet been confirmed.
Create a refund monitoring request to check that the refund was successful.
3. Add Refund Monitoring and Reconciliation Request
Using List Transfers, create a recurring request that looks for completed transactions in the Seller’s Profile.
Retrieve the status for refunds sent by using the profile_id, filtering by on the CRYPTO_WITHDRAWAL type and updated_at.gte parameters.
Best PracticeWe recommend to poll List Transfers globally at a set cadence (for example, at 1 second intervals), using slightly behind the last processed updated_at.gte as a synchronization checkpoint.
