Import a card

Send a card to MoonPay from your server, then buy crypto with it.

Send a card to MoonPay from your server and get a card id. Then quote and buy with it, as in Pay with card.

See the Going Live section for requirements you must meet before taking this integration to production.

Prerequisites

• Card import enabled on your MoonPay account. Contact your MoonPay account team to enable it.
• A PCI-compliant server to send card data from.
• A connected customer.

How it works

Each purchase needs a fresh CVC. Import a card once and store its id. Before each later purchase with that card, send the new CVC with Update the CVC. MoonPay keeps a CVC for one hour.

New customer

Returning customer

1. Connect the customer

   Connect the customer. Then get their access token with client.getCredentials() and pass it to your server.

   Hold the access token in memory only. Don’t log it or write it to disk.

2. Import the card

   Import a card the first time the customer pays with it. For a card you already imported, skip to Update the CVC.

   Call POST /platform/v1/payment-methods/cards from your server, with the customer’s access token as a Bearer token. The token needs the payment-methods.create scope.

   Send the request to MoonPay’s PCI proxy, not api.moonpay.com. Use the host that matches the access token:

   Mode	Host
   Live	https://secure.moonpay.com
   Test	https://secure-sandbox.moonpay.com

   We recommend sending the customer’s deviceIp and userAgent. MoonPay uses them for fraud checks.

   Import a card

   const res = await fetch(
     "https://secure.moonpay.com/platform/v1/payment-methods/cards",
     {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
         Authorization: `Bearer ${accessToken}`,
       },
       body: JSON.stringify({
         number: card.number,
         expirationMonth: "03",
         expirationYear: "2028",
         cvc: card.cvc,
         billingAddress: {
           street: "123 Main St",
           town: "New York",
           postCode: "10001",
           state: "NY",
           country: "USA",
         },
         deviceIp: "203.0.113.7",
         userAgent: customerUserAgent,
       }),
     },
   );
   
   const { data } = await res.json();
   

   Request body

   Field	Required	Description
   number	Yes	The card number.
   expirationMonth	Yes	2-digit month, for example "03".
   expirationYear	Yes	4-digit year, for example "2028".
   cvc	Yes	The card security code.
   billingAddress.street	Yes	Street line.
   billingAddress.subStreet	No	Second street line.
   billingAddress.town	Yes	Town or city.
   billingAddress.postCode	Yes	Postal code.
   billingAddress.state	No	State or province. Required for the United States and Canada.
   billingAddress.country	Yes	ISO 3166-1 alpha-3 country code, for example "USA".
   deviceIp	No	The customer’s device IP address, IPv4 or IPv6. Recommended.
   userAgent	No	The customer’s browser or app user agent, up to 1024 characters. Recommended.

   Responses

   • 201 Created: MoonPay added the card. Store data.id against the customer so you can update the CVC for later purchases.
   • 200 OK: the customer already has this card. MoonPay returns the same id and stores the new CVC. Retries are safe, and if you lose a card’s id, importing the card again returns it.

   Errors

   Status	code	Meaning
   400	card_not_supported	MoonPay doesn’t accept this card. Ask the customer for a different card.
   400	invalid_request	The request is invalid or MoonPay can’t add the card. errors lists any invalid fields.
   401	unauthorized	The access token is missing, invalid or expired, or a live token was sent to the test host.
   403	forbidden	The token lacks the payment-methods.create scope, card import isn’t enabled, or a live request didn’t come through the PCI proxy.
   409	conflict	The request conflicts with the customer’s current state.
   422	unprocessable_entity	MoonPay can’t add a card for this customer, for example because card payments aren’t available to them.

3. Update the CVC

   When a returning customer pays with a card you already imported, ask them for the CVC and send it with PATCH /platform/v1/payment-methods/cards/{cardId}/cvc. Use the card id from the import response as cardId. You don’t need to send the card number or billing address again.

   Call it from your server through the same PCI proxy host, with the customer’s access token. The token needs the payment-methods.create scope. MoonPay keeps the CVC for one hour, so send it shortly before the purchase.

   Update the CVC

   const res = await fetch(
     `https://secure.moonpay.com/platform/v1/payment-methods/cards/${cardId}/cvc`,
     {
       method: "PATCH",
       headers: {
         "Content-Type": "application/json",
         Authorization: `Bearer ${accessToken}`,
       },
       body: JSON.stringify({ cvc: card.cvc }),
     },
   );
   
   if (res.status !== 204) {
     // Handle the error. See the table below.
   }
   

   CVC update request body

   Field	Required	Description
   cvc	Yes	The card security code.

   CVC update responses

   • 204 No Content: MoonPay stored the new CVC. The response has no body.

   CVC update errors

   Status	code	Meaning
   400	invalid_request	cardId isn’t a valid card id, or cvc is missing or invalid.
   401	unauthorized	The access token is missing, invalid or expired, or a live token was sent to the test host.
   403	forbidden	The token lacks the payment-methods.create scope, card import isn’t enabled, or a live request didn’t come through the PCI proxy.
   404	not_found	The customer has no card with this id. Import the card again.

4. Quote and buy

   Get a quote with paymentMethod: { type: "card", id }, then run the purchase.

   • Get a quote
   • Execute the transaction, or use the buy button
   • Handle challenges
   • Track the transaction