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