Currently the v2 Onramp APIs are in private beta and only available to approved partners. Contact us to get early access.
The new v2 Onramp Order API enables you to build a native feeling onramp experience with Apple Pay where the user never leaves your app. It’s the fastest onramp experience available anywhere. Integrating takes only three steps:

​
Integration steps

1

Call the API

Call the Create Onramp Order API to get a quote and an Apple Pay payment link. You can fetch the list of available currencies from the Buy Options API.
2

Render the Apple Pay button

Render the Apple Pay button via the payment link URL in a webview in your app. The link can only be rendered in iOS apps.
3

Listen to events and update transaction status

Subscribe to post message events from the webview to listen for success/error messages. Use these events to notify the user when their transaction succeeds, or what type of error they encountered and how they might fix it.

​
Requirements

​
User verification

In order to provide an API driven native onramp experience, we rely on you, the app developer, to collect and verify the user’s email address and phone number in your request to the Create Onramp Order API. You must verify the user’s ownership of the email address and phone number, this can be done by sending an OTP using a vendor like Twilio or AWS SES. Additionally, the phone number must be re-verified at least every 60 days.

​
US only

We currently support the Apple Pay Onramp API for US users with valid US phone numbers. The phone number must be a real cell phone number, not a VoIP phone number.

​
iOS only

The Apple Pay onramp payment link can only be rendered in a webview in an iOS app. We currently do not support integrating this use case in web apps via iframe. If you’re building a web app based integration, let us know.

​
User gesture required

Apple requires that an Apple Pay session be created by a user gesture. This means that the user has to physically press the Apple Pay button we render within the webview. It cannot be programmatically triggered. Your users must accept Coinbase’s Guest Checkout Terms of Service, User Agreement and Privacy Policy prior to using Coinbase Onramp. It is your responsibility to clearly inform users that by proceeding with this payment they are agreeing to these policies.

​
Post message events

Payment links returned by the Create Order API are designed to be loaded within a webview so that your app can subscribe to post message events emitted by our web component. Events contain an error code and an error message. The message will be localized for the user so it can be displayed directly in your app UI. See the documentation of your webview library for details on how to consume post message events.
Post message event structure
{
  eventName: "<EVENT_NAME>",
  data: {
    errorCode: "<ERROR_CODE>",
    errorMessage: "<ERROR_MESSAGE>",
}

​
Events names

The following events are published by the Apple Pay button payment link.
​
onramp_api.load_pending
Emitted when Javascript is initialized and we have started fetching data required to render.
​
onramp_api.load_success
Emitted when the Apple Pay button is successfully rendered and ready for user interaction.
​
onramp_api.load_error
Emitted when an error occurred attempting to initialize the Apple Pay button. See the error message for more details. Some possible error codes are listed below.
Error CodeDescription
ERROR_CODE_INITThe payment link is no longer valid, call the Create Onramp Order endpoint to create a new one.
ERROR_CODE_GUEST_APPLE_PAY_NOT_SUPPORTEDThe user’s browser or device does not support Apple Pay.
ERROR_CODE_GUEST_APPLE_PAY_NOT_SETUPThe user has not set up Apple Pay on their device. Prompt the user to setup Apple Pay then try again.
​
onramp_api.commit_success
Emitted after the user presses the Apple Pay button if the transaction was successfully started.
​
onramp_api.commit_error
Emitted after the user presses the Apple Pay button if the transaction could not be started. See the error message for more details regarding the payment failure reasons. Some possible error codes are listed below.
Error CodeDescription
ERROR_CODE_GUEST_CARD_SOFT_DECLINEDThe user was declined by the bank. Please contact your bank or try again with a different debit card.

Users attempting to use Apple Cash will also get this error, but we cannot distinguish it from other bank decline cases.
ERROR_CODE_GUEST_INVALID_CARDInvalid card or billing address.
ERROR_CODE_GUEST_CARD_INSUFFICIENT_BALANCEThe debit card has an insufficient balance to process the transaction.
ERROR_CODE_GUEST_CARD_HARD_DECLINEDThe transaction was declined by the issuing bank of the card.
ERROR_CODE_GUEST_CARD_RISK_DECLINEDThe transaction was flagged by our risk rules and is unable to proceed.
ERROR_CODE_GUEST_REGION_MISMATCHThe region the user is located in is not supported.
ERROR_CODE_GUEST_PERMISSION_DENIEDThe user has been blocked from using onramp.
ERROR_CODE_GUEST_CARD_PREPAID_DECLINEDThe user tried to pay with a prepaid debit card, which is unsupported.
ERROR_CODE_GUEST_TRANSACTION_LIMITThis transaction would exceed the user’s weekly transaction limit.
ERROR_CODE_GUEST_TRANSACTION_COUNTThis transaction would exceed the user’s lifetime transaction count limit (currently 15).
​
onramp_api.cancel
Emitted if the user cancels the Apple Pay popup.
​
onramp_api.polling_start
If you keep the webview active in your app after receiving the onramp_api.commit_success message, the webview will poll our transaction status API automatically and report success or failure via the following two events.
​
onramp_api.polling_success
Emitted if the transaction completed successfully and funds have been sent to the destination wallet address.
​
onramp_api.polling_error
Emitted if there was an error processing the transaction. Some possible error codes are listed below.
Error CodeDescription
ERROR_CODE_GUEST_TRANSACTION_BUY_FAILEDWe were unable to complete the crypto purchase, likely due to a failed risk check. The user’s card will not be charged.
ERROR_CODE_GUEST_TRANSACTION_SEND_FAILEDWe were unable to send the funds to the user’s destination address, the user’s card will be refunded.
ERROR_CODE_GUEST_TRANSACTION_TRANSACTION_FAILEDAn internal error has occurred in Coinbase services, the Onramp team will be automatically notified to investigate.
ERROR_CODE_GUEST_TRANSACTION_AVS_VALIDATION_FAILEDWe were unable to process the transaction due to failure to validate the user’s billing address. Ask the user to verify their billing address with the bank card. The user’s card will not be charged.

​
Testing

You can test your integration with the Apple Pay Onramp API by creating sandbox orders. To create a sandbox order, just prefix the partnerUserRef parameter in your call to the Create Onramp Order API with the string sandbox-. Doing so will result in your Apple Pay transaction always succeeding, but your debit card will never be charged.