Execute Card Purchase

This endpoint allows purchasing cryptocurrency (USDC or USDT) using a credit card.

Purchase Process

When executing a card purchase, the user will be redirected to a cashier page to complete the payment, similar to the card verification process.

Technical Details

• Supported Coins: USDC, USDT
• Currency: USD
• Webhooks: This operation triggers the card_transaction_created and card_transaction_status_updated webhooks.

Authorization:

bearer

HTTP: bearer

HTTP Authorization Scheme: bearer

Headers:
  Authorization: APIKey {YOUR_API_KEY}

Endpoint

POST

/api/v2/cards/purchase

Request Body Sample (Using Saved Card)

{
  "accountId": "00000000-0000-0000-0000-000000000000",
  "amount": 100.00,
  "currency": "USD",
  "coin": "USDC",
  "cardId": "11111111-1111-1111-1111-111111111111",
  "paymentRedirectUrl": "https://myapp.com/payment/callback"
}

Request Body Sample (Using New Card)

{
  "accountId": "00000000-0000-0000-0000-000000000000",
  "amount": 100.00,
  "currency": "USD",
  "coin": "USDC",
  "card": {
    "cardNumber": "4111111111111111",
    "cardHolderName": "John Wick",
    "expMonth": 12,
    "expYear": 2028,
    "cvv": "123",
    "billingAddress": {
      "address1": "123 Main St",
      "address2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    },
    "saveCard": true
  },
  "paymentRedirectUrl": "https://myapp.com/payment/callback"
}

Request Body Schema

Field	Type	Description
accountId	string (uuid)	Required. The account ID for the purchase.
amount	number	Required. Amount in fiat currency to charge to the card. Minimum: $10.00. Example: 100.00.
currency	string	Required. Fiat currency. Currently only USD is supported.
coin	string	Required. Cryptocurrency to purchase. Possible values: USDC, USDT.
cardId	string (uuid)	Required if card not provided. The saved card ID to use. Card must have active status.
card	object	Required if cardId not provided. Card details for one-time or new card payment. See Card Object schema below.
paymentRedirectUrl	string (url)	Optional. URL where the user will be redirected after completing the payment. A status query parameter will be appended.

Card Object Schema

Field	Type	Description
cardNumber	string	Required. Card number (13-19 digits).
cardHolderName	string	Required. Cardholder name as it appears on the card.
expMonth	int	Required. Expiry month (1-12).
expYear	int	Required. Expiry year (4 digits, e.g., 2028).
cvv	string	Required. CVV/CVC code (3-4 digits).
billingAddress	object	Required. Billing address object with address1, address2, city, state, postalCode, country.
saveCard	boolean	Optional. If true, saves the card for future use. Default: false.

Response Sample

{
  "transactionId": "00000000-0000-0000-0000-000000000000",
  "status": "pending",
  "cashierUrl": "https://cashier.blockwyre.com/transaction/pay/xyz789abc123"
}

Response Schema

Field	Type	Description
transactionId	string (uuid)	Unique identifier for the transaction.
status	string	Transaction status. Initially pending.
cashierUrl	string (url)	URL where the user must complete the payment process. The user will be redirected to paymentRedirectUrl after completion.

Purchase Flow

After executing a card purchase, the user must complete the payment process:

1. API Response: Returns cashierUrl where the user must complete the payment.
2. User Action: User is redirected to cashierUrl to complete payment (e.g., 3D Secure, additional authentication).
3. Payment Processing: The card is charged for the amount.
4. Fee Deduction: Processing and network fees are deducted from the amount.
5. Completion: After payment, user is redirected to paymentRedirectUrl (if provided) with a status query parameter.
6. Crypto Delivery: If successful, the cryptocurrency (after fees) is credited to the user's wallet.

Example Flow

User requests: amount = $100.00, coin = USDC

Card is charged: $100.00
Fees deducted: $2.50 (processing + network)
Crypto delivered: 97.50 USDC

Payment Redirect Status

When the user completes the payment process, they will be redirected to the paymentRedirectUrl with a status query parameter appended.

Redirect URL Format

{paymentRedirectUrl}?status={status_value}

Example:

https://myapp.com/payment/callback?status=captured

Status Values

Status	Description
authorised	Card was successfully authorized. Order will complete once captured (within minutes).
refused	Card was refused/declined by card issuer.
failed	Failed attempt. Please try again or contact support.
captured	Card was successfully captured. Order will proceed.
cancelled	Payment was cancelled. Order will reverse.
refunded	Payment was refunded.

Saving a Card for Future Use

To save a card for future purchases, include "saveCard": true in the card object. After a successful transaction, the card will be saved and can be used in future purchases by referencing its cardId.

How to save a card:

1. Make a purchase using the card object with saveCard: true
2. After successful payment, the card is saved with active status
3. Use the List Credit Cards endpoint to retrieve the saved card's cardId
4. For future purchases, use cardId instead of providing full card details

Prerequisites

• If using cardId: Card must have active status and belong to the specified account.
• Account must have approved verification status.

Support and Resources

If you need assistance or have any questions, our support team is here to help. You can contact our support team at support@blockwyre.com.

Stay Updated

Stay up-to-date with the latest news, updates, and features from BlockWyre by following us on social media:

• Instagram: BlockWyre Instagram
• Twitter: BlockWyre Twitter
• Facebook: BlockWyre Facebook
• LinkedIn: BlockWyre LinkedIn

We are excited to have you on board and look forward to seeing how you leverage BlockWyre's powerful tools to enhance your financial operations. Happy integrating!