Skip to main content
Version: v1

Set Up Payment Method

The Set Up Payment Method API allows merchants to add a payment method using the merchant-pci and user scope. The merchant-pci scope uses the token endpoint and supports adding payment methods via Interactive Voice Response (IVR) and user scopes enables user to add payment method via On Screen Entry.

Quick Reference
  • API Endpoint: POST v1/setup-payment-methods
    • Supported Scope: user
    • Allowed Session Modes - PAYMENT_WITH_WALLET, PAYMENT_METHOD_ENTRY WALLET
  • API Endpoint: POST v1/token/setup-payment-methods
    • Supported Scope: merchant-pci
  • Payment Method Types: CARD, BANK_ACCOUNT
  • Key Fields: customer, paymentMethod, paymentMethodDetails, manufacturerCard
  • Behavior:
    • If customer not found, creates a new profile and links the payment method
    • If customer found, associates payment method with existing profile
    • ⚠️ Manufacturer Card: Not supported (flag is ignored) in merchant-pci scope
  • Error Codes: Refer SetUp Payment Method Error Codes
  • Notifications: Refer Webhooks

Handling Payment Method Setup​

  • Add a card or bank account for a customer
  • If the customer does not exist, a new profile is created
  • Manufacturer cards are not supported via this merchant-pci scope
  • ⚠️ Default flag and manufacturer details are not honoured while adding duplicate payment method. Learn More

Add Card Example​

PCI Scope​

Sample Request – Add Card - PCI Scope
{
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "customer": {
    // ...customer fields...
  },
  "agent": {
    // ...agent fields...
  },
  "paymentMethod": {
    "type": "CARD",
    "vendorPaymentMethodId": "string",
    "vendor": "STRIPE",
    "default": true,
    "paymentMethodDetails": {
      "type": "CARD",
      "nameOnCard": "string",
      "manufacturerCard": false,

    }
  }
}

User Scope​

Regular Card​

Sample Request – Add Regular Card - User Scope
{
  "paymentMethodType": "CARD",
  "paymentMethod": {
    "type": "CARD",
    "vendorPaymentMethodId": "string",
    "vendor": "STRIPE",
    "nickname": "string",
    "sourceProvider": {
      "name": "CCG"
    },
    "agent": {
      // agent details
    },
    "paymentMethodDetails": {
      "type": "CARD",
      "last4": "string",
      "cardBrand": "VISA",
      "expiryYear": 0,
      "nameOnCard": "string",
      "expiryMonth": 0,
      "vendorPaymentMethodFingerprint": "string"
    },
    "default": true
  }
}

Manufacturer Card​

Adding Manufacturer card through manufacturerCard flag​

Note: Agent object is required if manufacturerCard flag is passed

Sample Request – Add Manufacturer Card - User Scope
{
  "paymentMethodType": "CARD",
  "paymentMethod": {
    "type": "CARD",
    "vendorPaymentMethodId": "string",
    "vendor": "STRIPE",
    "nickname": "string",
    "sourceProvider": {
      "name": "CCG"
    },
    "agent": {
      // agent details
    },
    "paymentMethodDetails": {
      "type": "CARD",
      "last4": "string",
      "cardBrand": "VISA",
      "expiryYear": 0,
      "nameOnCard": "string",
      "expiryMonth": 0,
      "vendorPaymentMethodFingerprint": "string",
      "manufacturerCard" : true
    },
    "default": false
  }
}
Adding Manufacturer card through cardCategories object​

Note:

  • Agent object is not required if cardCategories is passed
  • When both cardCategories and manufacturerCard is present, system will use cardCategories
Sample Request – Add Manufacturer Card - User Scope
{
  "paymentMethodType": "CARD",
  "paymentMethod": {
    "type": "CARD",
    "vendorPaymentMethodId": "string",
    "vendor": "STRIPE",
    "nickname": "string",
    "sourceProvider": {
      "name": "CCG"
    },
    "paymentMethodDetails": {
      "type": "CARD",
      "last4": "string",
      "cardBrand": "VISA",
      "expiryYear": 0,
      "nameOnCard": "string",
      "expiryMonth": 0,
      "vendorPaymentMethodFingerprint": "string",
      "manufacturerCard" : false,
      "cardCategories":[{
           "type": "MANUFACTURER_CARD",
            "medication":[
              {
                "label":"string",
                "value":"string"
              }
            ]
      }       
      ]
    },
    "default": false
  }
}

Add Bank Account Example​

PCI Scope​

Sample Request – Add Bank Account - PCI Scope
{
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "customer": {
    // ...customer fields...
  },
  "paymentMethod": {
    "type": "BANK_ACCOUNT",
    "default": true,
    "nickname": "HealthSavingsAccount",
    "vendor": "STRIPE",
    "agent": null,
    "paymentMethodDetails": {
      "type": "BANK_ACCOUNT",
      "accountNumber": "000123456789",
      "routingNumber": "110000000",
      "accountType": "savings",
      "nameOnAccount": "Syamala"
    }
  }
}

User Scope​

Sample Request – Add Bank Account - User Scope
{
  "paymentMethodType": "BANK_ACCOUNT",
  "paymentMethod": {
    "type": "BANK_ACCOUNT",
    "vendor": "STRIPE",
    "nickname": "My Checking Account",
    "paymentMethodDetails": {
      "type": "BANK_ACCOUNT",
      "routingNumber": "110000000",
      "accountNumber": "000123456789",
      "accountType": "checking",
      "nameOnAccount": "John Doe"
    },
    "default": true
  }
}

Sample Response​

Sample Response
{
  "url": "string",
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "platformVendorMerchantId": "string",
    "vendorSetupPaymentMethodSecret": "string",
    "status": "WAITING_FOR_CUSTOMER_CREATION"
    "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
    "paymentMethodType": "CARD|BANK_ACCOUNT",
    "error": {
      "errorGroup": "CUSTOMER_ERROR",
      "errorCode": "string",
      "message": "string",
      "httpStatus": "400 BAD_REQUEST"
    },
    "warning": {
      "code": "string",
      "title": "string",
      "description": "string"
    }
  }
}

Notifications​

PAYMENT_METHOD_ADDED event will be triggered to merchants if requested. Refer Webhooks

Error Handling​

Refer SetUp Payment Method Error Codes