Guides

Ordering a VISA Card

Suggest Edits

Ordering a VISA card through the API involves a series of steps to select and request a card. This guide provides a detailed walkthrough of each step, including the relevant API endpoints and expected responses.


To order a VISA card through the API, follow these steps:

  1. Retrieve Available Card Offers: Fetch a list of available card options, including their types and designs.
  2. Select Card Type and Design: Choose between virtual or physical card types and select the desired card design.
  3. Submit a Card Issuance Request: Initiate a request to issue a new card by providing the necessary details.
  4. Handle Personally Identifiable Information (PII): Ensure that any Personally Identifiable Information (PII) is encrypted and handled in accordance with security best practices.
  5. Confirm Delivery Address for Physical Cards: For physical cards, provide and verify the delivery address to ensure accurate delivery.
  6. Process Webhook Events for Card Request Invoices: Handle webhook events related to invoice creation and payment processing for card requests.
  7. Track Card Request Status: Monitor the status of your card request to ensure it is being processed as expected.

Steps to Order a VISA Card

Step 1: Explore Available Card Offers

Start by retrieving a list of available card options from your financial service provider. This list will include various types of cards, such as virtual or physical, and may feature customizable designs.

API Endpoint: GET card-holder/cardoffer

This endpoint provides details about all card offers available to the user, including card providers, designs, and pricing information.

Example Response:

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", // unique identifier for the card offer.
    "provider": "PFSCARD", // name of the card provider.
    "allowedCardDesigns": [ // list of allowed card designs.
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", // unique identifier for the card design.
        "userId": "string", // user identifier.
        "accountId": "string", // account identifier.
        "additionalCardInfo": {}, // additional card information.
        "status": "INIT" // status of the card design.
      }
    ],
    "allowUserPrimaryCardname": true, // whether primary card name customization is allowed.
    "allowUserSecondaryCardname": true, // whether secondary card name customization is allowed.
    "allowVirtualCards": true, // whether virtual cards are available.
    "allowPhysicalCards": true, // whether physical cards are available.
    "firstVirtualPriceCurrency": "USD", // currency for the first virtual card price.
    "firstVirtualPriceAmount": 0, // amount for the first virtual card price.
    "virtualPriceCurrency": "USD", // currency for subsequent virtual card prices.
    "virtualPriceAmount": 2, // amount for subsequent virtual card prices.
    "firstPhysicalPriceCurrency": "USD", // currency for the first physical card price.
    "firstPhysicalPriceAmount": 5, // amount for the first physical card price.
    "physicalPriceCurrency": "USD", // currency for subsequent physical card prices.
    "physicalPriceAmount": 10 // amount for subsequent physical card prices.
  }
]

Step 2: Select Card Type and Design

Based on the available offers, choose the card type and design that best suits your needs:

  • Virtual Cards: Ideal for online payments and are often issued instantly.
  • Physical Cards: Suitable for both online and offline payments; requires a delivery address.

Step 3: Submit a Card Request

Submit a request to issue a new card with the required details.

API Endpoint: POST card-holder/cardrequest

Use this endpoint to create a new card request. Ensure all required data is provided and that Personally Identifiable Information (PII) is encrypted if needed.

Example Request:

{
  "card_offer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", // unique identifier of the selected card offer.
  "card_type": "VIRTUAL", // type of card to be created (e.g., VIRTUAL or PHYSICAL).
  "account_id": "account_12345", // external account ID associated with the card request.
  "preferred_cardname": "John Doe", // preferred name to be printed on the card.
  "secondary_cardname": "Business Card", // optional secondary name for the card.
  "encrypted_pii": "encryptedPIIData", // encrypted Personally Identifiable Information (PII) data, if required.
  "card_design_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" // unique identifier for the card design.
}

Step 4: Confirm Delivery Address for Physical Cards

For physical cards, provide a valid delivery address to ensure proper delivery.

Example Request:

{
  "deliveryAddress": {
    "country": "GBR", // ISO Alpha-3 country code.
    "postCode": "SW1A 1AA", // postal code of the delivery location.
    "state": "MA", // state or region.
    "town": "London", // city or town.
    "street": "Downing Street", // primary street address.
    "subStreet": "10", // additional street information.
    "buildingName": "Buckingham Palace", // name of the building.
    "flatNumber": "1", // flat number.
    "buildingNumber": "10", // building number.
    "confirmed": true // whether the address has been confirmed.
  }
}

Ensure that the delivery address is accurate and confirmed to avoid issues with card delivery.


Step 5: Process Webhook Event for Card Request Invoice

If your card request involves an invoice (for example, for paid cards or special processing fees), you need to handle webhook events related to these invoices to update the status of the card request properly.

API Endpoint: POST /card-holder/invoice/webhook

This endpoint processes webhook events related to card request invoices. The endpoint should be called by the external system to notify your application about the creation, update, or payment status of an invoice.

Query Parameters:

  • invoiceDto (object, required): The invoice data to be processed by the webhook.

InvoiceDto Object:

  • externalClientId (string): Client ID in the external system, used for linking invoices to external clients.
  • id (string): Unique identifier for the invoice.
  • amount (number, required): The amount required to complete the invoice.
  • currency (string, required): Currency in ISO format used for the invoice.
  • paymentDate (int64): The date when the invoice was paid, represented as a timestamp.
  • type (string, required): Specifies the type of invoice.
  • status (string): Current status of the invoice, such as INIT, PENDING, COMPLETED, etc.
  • payments (array): List of payments associated with this invoice.
  • discountCode (string): Discount code applied to this invoice.

This step ensures that your system remains up-to-date with any invoice-related events, facilitating accurate processing and fulfillment of card requests.


Step 6: Track Your Card Request

Monitor the status of your card request to stay updated on its progress.

API Endpoint: GET card-holder/cardrequest/card

Retrieve the status of your card requests, which can include statuses such as "INIT", "APPROVED", or other relevant stages.

Example Request:

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", // unique identifier for the card request.
    "provider": "PFSCARD", // name of the card provider.
    "accountId": "account_12345", // external account ID.
    "status": "INIT", // status of the card request.
    "createdDate": "2024-09-03T06:38:31.104Z", // date and time the request was created.
    "cardName": "John Doe", // name printed on the card.
    "secondaryCardName": "Business Card", // optional secondary name on the card.
    "cardType": "VIRTUAL", // type of card requested.
    "cardDesignId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", // unique identifier for the card design.
    "deliveryAddress": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", // unique identifier for the delivery address.
      "country": "GBR", // ISO Alpha-3 country code.
      "postCode": "SW1A 1AA", // postal code of the delivery location.
      "state": "MA", // state or region.
      "town": "London", // city or town.
      "street": "Downing Street", // primary street address.
      "subStreet": "10", // additional street information.
      "buildingName": "Buckingham Palace", // name of the building.
      "flatNumber": "1", // flat number.
      "buildingNumber": "10", // building number.
      "confirmed": true // whether the address has been confirmed.
    }
  }
]

Regularly checking the status ensures you stay informed about any updates or necessary actions.



Conclusion

Ordering a VISA card involves several critical steps: retrieving card offers, selecting the type and design, submitting a request, confirming delivery details, handling invoice-related webhooks, and tracking the request status. By following these steps and using the appropriate API endpoints, you can efficiently manage the card ordering process and ensure you receive the card that meets your needs.

Updated 2 months ago