Customer Payment Methods

Customer Payment Methods represent chargeable payment methods like credit cards or direct debit mandates belonging to a customer. You can save them to Customer objects to store instrument details for future payments.

The Customer Payment Method object

Required attributes

Name
_id
Type
string
Description
The ID of the payment method
Name
status
Type
enum(ACTIVE, DELETED, EXPIRED)
Description
The status of the payment method
Name
sellerId
Type
string
Description
The ID of the seller this payment method
Name
primary
Type
boolean
Description
Whether the payment method is primary
Name
active
Type
boolean
Description
Whether the payment method is primary
Name
gatewayId
Type
string
Description
The ID of the attached payment gateway or additional payment method

Optional attributes

Name
data
Type
object
Description
Whether the payment method is primary
Name
paymentDetails
Type
object
Description
Whether the payment method is primary
Name
gatewayType
Type
enum(stripe, paypal, adyen, custom, cardconnect, worldline, shift4, authorizenet, wallee, square, payfast, touchnet, transact, unzer, monext, vivenuPayments, ebanx, rapyd, momentusPayments, paymob, additional-payment-method)
Description
The type of the payment gateway associated to this method
Name
channels
Type
array<oneOf>
Description
The type of the customer payment method
One of — Only one of the following types
enum(onSession)
Name
createdAt
Type
string date-time
Description
The created ISO timestamp
Name
updatedAt
Type
string date-time
Description
The last updated ISO timestamp

Example

{
  "_id": "507f191e810c19729de860ea",
  "status": "ACTIVE",
  "sellerId": "507f191e810c19729de860ea",
  "primary": true,
  "active": true,
  "gatewayId": "507f191e810c19729de860ea",
  "data": {},
  "paymentDetails": {},
  "gatewayType": "stripe",
  "channels": [
    "onSession"
  ],
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z"
}

GET/api/customers/:id/payment-methods

Get payment methods for customer

Query parameters

Optional query parameters

Name
channel
Type
string
Description
Channel the methods are used for
Name
primary
Type
boolean
Description
Whether the payment method is primary or not
Name
active
Type
boolean
Description
Whether the payment method is active or not
Name
gatewayId
Type
string
Description
The ID of the payment gateway or additional payment method which the payment method belongs to
Name
paymentGatewayChannels
Type
array<enum(online, pos, subscription, subscription_internal)>
Description
The allowed payment gateway channels
Name
status
Type
array<enum(ACTIVE, DELETED, EXPIRED)>
Description

Request

GET

/api/customers/:id/payment-methods

const response = await fetch('https://vivenu.com/api/customers/507f191e810c19729de860ea/payment-methods?channel=value&primary=true&active=true&gatewayId=507f191e810c19729de860ea&paymentGatewayChannels=value1%2Cvalue2&status=value1%2Cvalue2', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

[
  {
    "_id": "507f191e810c19729de860ea",
    "status": "ACTIVE",
    "sellerId": "507f191e810c19729de860ea",
    "primary": true,
    "active": true,
    "gatewayId": "507f191e810c19729de860ea",
    "data": {},
    "paymentDetails": {},
    "gatewayType": "stripe",
    "channels": [
      "onSession"
    ],
    "createdAt": "2030-01-23T23:00:00.123Z",
    "updatedAt": "2030-01-23T23:00:00.123Z"
  }
]

POST/api/customers/:id/payment-methods

Create a customer payment method

Payload

Any of — Some of the following types

Required attributes

Name
data
Type
object
Description
Required nested attributes (3)
Name
iban
Type
object
Description
The IBAN of the customer payment method.
Name
bic
Type
object
Description
The BIC of the customer payment method.
Name
accountHolderName
Type
string
Description
The account holder name of the customer payment method.
Name
gatewayId
Type
string
Description
The ID of the payment gateway or additional payment method which the payment method belongs to

Request

POST

/api/customers/:id/payment-methods

const response = await fetch('https://vivenu.com/api/customers/507f191e810c19729de860ea/payment-methods', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(  {
    "data": {
      "accountHolderName": "string"
    },
    "gatewayId": "507f191e810c19729de860ea"
  }),
})

const data = await response.json()

Response (201)

{
  "_id": "507f191e810c19729de860ea",
  "status": "ACTIVE",
  "sellerId": "507f191e810c19729de860ea",
  "primary": true,
  "active": true,
  "gatewayId": "507f191e810c19729de860ea",
  "data": {},
  "paymentDetails": {},
  "gatewayType": "stripe",
  "channels": [
    "onSession"
  ],
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z"
}

POST/api/customers/:customerId/payment-methods/:paymentMethodId/primary

Set customer payment method to primary

Request

POST

/api/customers/:customerId/payment-methods/:paymentMethodId/primary

const response = await fetch('https://vivenu.com/api/customers/507f191e810c19729de860ea/payment-methods/507f191e810c19729de860ea/primary', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "status": "ACTIVE",
  "sellerId": "507f191e810c19729de860ea",
  "primary": true,
  "active": true,
  "gatewayId": "507f191e810c19729de860ea",
  "data": {},
  "paymentDetails": {},
  "gatewayType": "stripe",
  "channels": [
    "onSession"
  ],
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z"
}