Create an Onramp Transaction
An onramp transaction refers to the process of converting traditional fiat currency (such as pesos or reais) into digital assets like USDT or USDC. This transaction serves as a gateway to the digital asset market.
After you have created a customer and the customer's kyc(b) has been approved, you may then execute an onramp transaction. The exchange of fiat for cryptocurrency. Onramp from a Fiat account to a Blockchain wallet. With an approved customerid and a quoteid you may execute an onramp transaction.
Virtual Account Onramp
When Alfred approves a customer’s KYC(B), a virtual account is automatically generated for that customer in the supported countries. This virtual account can then be retrieved and displayed within your native experience, giving users an account to receive deposits. Any deposits made into this account are automatically converted into a USDC(T) deposit in the customer’s personal wallet.
This is the Liquidation Address feature we provide. The onramp deposit account is the virtual fiat account created by Alfred, which receives the fiat deposit for each onramp generated for that specific customer.
If the onramp is generated in a country where Alfred does not yet offer virtual accounts, the deposit account will instead be an account under Alfred’s name. All deposits are routed to this account and internally consolidated by customer.
It’s important to note that in this case, the deposit amount must exactly match the amount specified in the QuoteID. If there is any discrepancy, the user will need to resolve the payment with customer support.
Onramp Example
Request Body
curl --request POST \
\--url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/onramp
\--header 'Content-Type: application/json' \
\--header 'accept: */*' \
\--header 'api-key: xxxxxxx' \
\--header 'api-secret: xxxxxxx' \
\--data {
"customerId": "9efc6db2-4d2f-4ed4-92a1-325f10ab5321",
"quoteId": "388fccc8-8ef5-4fd4-a387-57b6e9ee4565",
"fromCurrency": "MXN",
"toCurrency": "USDC",
"amount": "35000",
"chain": "XLM",
"depositAddress": "GC5MS2YGIRP3GKB7K2OUZ3VS3RWIQHQPENYCMZP2E2K5NUQAMAKH6UHE",
"paymentMethodType": "BANK"
}curl --request POST \
\--url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/onramp
\--header 'Content-Type: application/json' \
\--header 'accept: */*' \
\--header 'api-key: xxxxxxx' \
\--header 'api-secret: xxxxxxx' \
\--data {
"customerId": "4d718950-b39f-4020-a4c1-8861c7050beb",
"quoteId": "891d2c38-6e3e-42e5-a6b4-a8d2df8cf55f",
"fromCurrency": "BRL",
"toCurrency": "USDC",
"amount": "35000",
"chain": "XLM",
"depositAddress": "GC5MS2YGIRP3GKB7K2OUZ3VS3RWIQHQPENYCMZP2E2K5NUQAMAKH6UHE",
"paymentMethodType": "BANK"
}curl --request POST \
\--url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/onramp
\--header 'Content-Type: application/json' \
\--header 'accept: */*' \
\--header 'api-key: xxxxxxx' \
\--header 'api-secret: xxxxxxx' \
\--data {
"customerId": "572449f0-c2a8-429f-b198-499704aed866",
"quoteId": "3ab1cb10-c8e6-4853-b2b7-e9bc25e08a0f",
"fromCurrency": "ARS",
"toCurrency": "USDC",
"amount": "35000",
"chain": "XLM",
"depositAddress": "GC5MS2YGIRP3GKB7K2OUZ3VS3RWIQHQPENYCMZP2E2K5NUQAMAKH6UHE",
"paymentMethodType": "BANK"
}
curl --request POST \
\--url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/onramp
\--header 'Content-Type: application/json' \
\--header 'accept: */*' \
\--header 'api-key: xxxxxxx' \
\--header 'api-secret: xxxxxxx' \
\--data {
"customerId": "73fdbcab-f50e-42cf-968e-62038c26f27a",
"quoteId": "65429dda-e9e8-4ac0-9543-fceea01098d5",
"fromCurrency": "COP",
"toCurrency": "USDC",
"amount": "35000",
"chain": "XLM",
"depositAddress": "GC5MS2YGIRP3GKB7K2OUZ3VS3RWIQHQPENYCMZP2E2K5NUQAMAKH6UHE",
"paymentMethodType": "BANK",
"metadata": {
"bankId": "1558",
}
}curl --request POST \
\--url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/onramp
\--header 'Content-Type: application/json' \
\--header 'accept: */*' \
\--header 'api-key: xxxxxxx' \
\--header 'api-secret: xxxxxxx' \
\--data {
"customerId": "3e2b09c3-8f83-4396-b121-3ca25f8a2f65",
"quoteId": "9efc6db2-4d2f-4ed4-92a1-325f10ab5321",
"fromCurrency": "USD",
"toCurrency": "USDT",
"amount": "100",
"chain": "TRX",
"paymentMethodType": "BANK",
"depositAddress": "GC5MS2YGIRP3GKB7K2OUZ3VS3RWIQHQPENYCMZP2E2K5NUQAMAKH6UHE"
}Response Example
{
"transaction": {
"transactionId": "46b33510-9ddd-4e3e-becb-db8d3b290ec7",
"customerId": "9efc6db2-4d2f-4ed4-92a1-325f10ab5321",
"createdAt": "2025-08-19T19:41:04.821Z",
"updatedAt": "2025-08-19T19:41:04.821Z",
"quoteId": "388fccc8-8ef5-4fd4-a387-57b6e9ee4565",
"fromCurrency": "MXN",
"toCurrency": "USDC",
"fromAmount": "35000",
"toAmount": "1806.15161",
"status": "CREATED",
"chain": "XLM",
"paymentMethodType": "BANK",
"txHash": null,
"depositAddress": "GC5MS2YGIRP3GKB7K2OUZ3VS3RWIQHQPENYCMZP2E2K5NUQAMAKH6UHE",
"externalId": "",
"memo": "",
"metadata": {
"bankId": "1558",
},
"quote": {
"quoteId": "388fccc8-8ef5-4fd4-a387-57b6e9ee4565",
"fromCurrency": "MXN",
"toCurrency": "USDC",
"fromAmount": "35000",
"toAmount": "1806.15161",
"expiration": "2025-08-19T20:40:30.705Z",
"rate": "19.26",
"metadata": {},
"fees": [
{
"type": "commissionFee",
"amount": "175",
"currency": "MXN"
},
{
"type": "processingFee",
"amount": "0",
"currency": "MXN"
},
{
"type": "taxFee",
"amount": "0",
"currency": "MXN"
},
{
"type": "networkFee",
"amount": "38.52",
"currency": "MXN"
}
]
}
},
"fiatPaymentInstructions": {
"paymentType": "SPEI",
"clabe": "684180125006228146",
"reference": "J8CP3AL",
"expirationDate": "2025-08-19T19:51:00.470Z",
"paymentDescription": "SPEI account details to deposit.",
"bankName": "Transfer",
"accountHolderName": "Cell Pay S.A.P.I de C.V"
}
}{
"transaction": {
"transactionId": "dc574ef1-92a9-4be5-ac0e-1e188e327271",
"customerId": "4d718950-b39f-4020-a4c1-8861c7050beb",
"createdAt": "2025-08-19T19:43:12.714Z",
"updatedAt": "2025-08-19T19:43:12.714Z",
"quoteId": "891d2c38-6e3e-42e5-a6b4-a8d2df8cf55f",
"fromCurrency": "BRL",
"toCurrency": "USDC",
"fromAmount": "35000",
"toAmount": "6656.76686",
"status": "CREATED",
"chain": "XLM",
"paymentMethodType": "BANK",
"txHash": null,
"depositAddress": "GC5MS2YGIRP3GKB7K2OUZ3VS3RWIQHQPENYCMZP2E2K5NUQAMAKH6UHE",
"externalId": "",
"memo": "",
"metadata": null,
"quote": {
"quoteId": "891d2c38-6e3e-42e5-a6b4-a8d2df8cf55f",
"fromCurrency": "BRL",
"toCurrency": "USDC",
"fromAmount": "35000",
"toAmount": "6656.76686",
"expiration": "2025-08-19T20:43:04.493Z",
"rate": "5.19",
"metadata": {},
"fees": [
{
"type": "commissionFee",
"amount": "308",
"currency": "BRL"
},
{
"type": "processingFee",
"amount": "0",
"currency": "BRL"
},
{
"type": "taxFee",
"amount": "133",
"currency": "BRL"
},
{
"type": "networkFee",
"amount": "10.38",
"currency": "BRL"
}
]
}
},
"fiatPaymentInstructions": {
"paymentType": "PIX",
"qrCode": "00020101021226790014br.gov.bcb.pix2557brcode.starkinfra.com/v2/0f1e3aae1536460c86d86c46b0e814985204000053039865802BR5909Transfero6014Rio de Janeiro62070503***63049803",
"qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAVkAAAFZAQAAAAAaiWF2AAAE0UlEQVR4nO1aQY6jQAx0lEMfeUL/JHwMKUh8LPyEJ3DkgPC6qpokO7srzWH34FU4IHooRorbbZfLNv/+NdoH/AF/wP8AvJrZZbVa5rj5vA61uE8et7Fav96X8ghESQy+u88+LdvFdyyHatbt1S6wwLxelzLHQ2bwYFwGxH0zuy7Wx2dbv169PLrdaKb04Hji7Yi3G3bfbp2HhbD7/wM4lvHiLkPENQA8LfR2zw6GP+ML9x0nNDbZ4xb+vFfXIf7i/NnAjEjc1T/cfglfucDnZdhuhKUKayzyAwTf3yWgVOAxfmwXTw+7u91wi7CE/WWAipxyxN9KXnD8aDo1Yyw+qxtTJbKLA+eP7mmNlGAcWHfkxh2eTWswQF1xkuP5FrYqicERc44Ir5Egx1rwBLssjLux9AXU4GmNhOA4knBbD7cdKlkBNxlMgUnTRA0Sg3cxAP6NvgtepzAMz3ac5MXzguNwBmS0Lb5AvtRS9Fz+3DeinhTsxO345cFuHiA7s6KUuI/CsCcGTwhGLD1cZ1VJhEcXYUnOkBgMNueudBK+y0winlNhiNj9iMCeGOxa4guYRDZAyGVhPMgjSmIwmBvZa+AYbVvVwSLk3PPM4DirF/HTyUkNwqkHHl0nZwjPHi0zOIgcYg4iEjOJ2PrWo7YiK3hPQAnBKDOQL/EWSZMlI/y5QyaJf7C987qMYKaOgDBz9q0m5p5T2YE1XiQwIRi1FTY5cM04zKFgQaJ58PFaEoN3MXMoqca6US4AHssKEgrk0xoJwZQScWCRICmdIpNU+vNmcoHIpnnBeDrwgtLGrAhMNSA2vkdsutkrpyQEqxyWdmOUil/6BmV/FsuJwY7K8HRgCfusP0DuwhoTly/nTwgGF4BY0/ozriVYkIsfzOtLzsoIZslolYKGe/v5C8MSkk2zVWowQ62xFTU39/aTs+pdLYnBUmeodsMksAEKDvZsEIzo1J4ZDAbATGLs2RjBG3kdhADqjiUvmAIxom1P7sPtRp18qB8Fjk7ROC8YYrC2m2+hAXTUPEaTnHp567UlBPuoJ5Jy+K6qrHBl8Dopci9/TgjGJiPmIEsik0QdhVoD1hABArl7a62mA8MaB+rfA4wH0kYcWFrDoJ+q9eapwUonxrPaQ6ZCMHoNMNDRPS8YB/bouLVhCEr8KEIKiy6XLOdLYrDabFAwVgqNI+wCz0adfJGtng39jOCwhnz3ojmFEUz1Ku0GWri/+3NKsDXhDQIOzyrVAOhSVbJ/a+1nBSsikb4hX5o1wUpNOFNOcU8MnkDpWOqzH9V2X3T1OS9VUoOt5Q/2f2EN48yJulBOkSM3mCrxObYQ19lrE2elC6QGL6XVUVY3jl2yv++SihWMnhk2I3hnF8o5ksG4y1KrDZeGhThTVPKCUVcwdTw0bsKtnUjzaKb6EzNPCTaOB7OlJvZKQWNWLcm+qVliMK91qG0EypglVVsZju5CVpAYfLICTM86bxQ5OAxFUadIWM0Lvp+zM4A4R/TbzAmOqS8/8bqMYM4/X1VMYSwKDjyo18btxtLSgzV7uShLHpzha/6szlR6sFEDOAkQndrZnhrtHANLC763CfZ2LiOxIORSoeLw+hcRNR/Yznka1FanITQLpnRyTkklBX/7+oA/4A/474N/AKwwxhxvlycYAAAAAElFTkSuQmCC",
"pixKey": "6bd15e75-4813-464d-b47e-66cf5c803e1b",
"reference": "787TG25081943115464717FFCC",
"expirationDate": "2025-08-19T19:53:09.919Z"
}
}{
"transaction": {
"transactionId": "8db51d15-75a3-4441-803e-dfd9fedcf621",
"customerId": "572449f0-c2a8-429f-b198-499704aed866",
"createdAt": "2025-08-19T19:41:59.813Z",
"updatedAt": "2025-08-19T19:41:59.813Z",
"quoteId": "3ab1cb10-c8e6-4853-b2b7-e9bc25e08a0f",
"fromCurrency": "ARS",
"toCurrency": "USDC",
"fromAmount": "35000",
"toAmount": "27.032446",
"status": "CREATED",
"chain": "XLM",
"paymentMethodType": "BANK",
"txHash": null,
"depositAddress": "GC5MS2YGIRP3GKB7K2OUZ3VS3RWIQHQPENYCMZP2E2K5NUQAMAKH6UHE",
"externalId": "",
"memo": "",
"metadata": null,
"quote": {
"quoteId": "3ab1cb10-c8e6-4853-b2b7-e9bc25e08a0f",
"fromCurrency": "ARS",
"toCurrency": "USDC",
"fromAmount": "35000",
"toAmount": "27.032446",
"expiration": "2025-08-19T20:41:36.897Z",
"rate": "1199.52",
"metadata": {},
"fees": [
{
"type": "commissionFee",
"amount": "175",
"currency": "ARS"
},
{
"type": "processingFee",
"amount": "0",
"currency": "ARS"
},
{
"type": "taxFee",
"amount": "0",
"currency": "ARS"
},
{
"type": "networkFee",
"amount": "2399.04",
"currency": "ARS"
}
]
}
},
"fiatPaymentInstructions": {
"paymentType": "ARS_BANK_TRANSFER",
"cvu": "0000053600000023823604",
"alias": "ESTRAGO.PASTO.LUTERO",
"paymentDescription": "Deposit payment to the following account number or alias.",
"reference": "GMJ3JUH",
"expirationDate": "2025-08-19T19:51:59.733Z"
}
}Webhook status updates
To receive transaction status updates, please provide the Alfred onboarding team with the URL where you would like webhooks to be delivered. The following webhooks will be sent for Onramp transactions.
Onramp event type statuses
| status | Description | Metadata |
|---|---|---|
| FIAT_DEPOSIT_RECEIVED | Partner has received customer fiat funds. If a quote from original transaction is expired, send a new quoteId in metadata. | null |
| TRADE_COMPLETED | Trade of local fiat to USDT has been completed. | null |
| ON_CHAIN_INITIATED | Partner initiated on chain send to customer wallet address. | {"txHash":string} |
| ON_CHAIN_COMPLETED | On chain send to customer wallet address is complete. | {"txHash": string} |
| FAILED | Onramp failed for a partner specific reason. Partner to provide set of failure reasons | {"failureReason": string, "txHash": string(optional)} |
Updated 8 days ago