Private API reference

Payment Method

Private Payment Method API endpoints

Endpoints

POST/payment_methods
GET/payment_methods/{payment_method_id}
DELETE/payment_methods/{payment_method_id}

Create a payment method

POST /payment_methods

Store a payment method for a customer of your shop from a gateway-side token. The token is exchanged with the gateway; only the shape of token is validated up front, so a token the gateway rejects surfaces as a server error rather than a validation error. When the customer has no default payment method yet and the gateway is in live mode, the new payment method becomes the default.

Request body

customer_idRequiredinteger

ID of the customer the payment method belongs to.

gateway_idRequiredinteger

ID of a payment gateway belonging to your shop.

tokenRequiredstring

Gateway-side token for the payment instrument, for example a Stripe payment method ID or a Braintree nonce. It is exchanged with the gateway on the spot.

ReturnsPaymentMethod

Payment method object response

Error responses

422object

Validation failed, for example a customer_id that is not a customer of your shop, a missing token, or a gateway_id that does not belong to your shop.

curl -X POST https://api.subbly.co/private/v1/payment_methods \
  -H 'X-API-KEY: <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "customer_id": 1,
  "gateway_id": 1,
  "token": "token"
}'

Response

{
  "id": 567,
  "type": "card",
  "identifier": "4242",
  "currencies": [
    "USD",
    "EUR"
  ],
  "card": {
    "last_four": "4242",
    "expiry_month": "2",
    "expiry_year": "2099",
    "type": "credit",
    "brand": "visa"
  },
  "ideal": {
    "bank": "ING",
    "bic": "INGBNL2A",
    "email": "test@subbly.co",
    "name": "John Doe"
  },
  "bancontact": {
    "email": "test@subbly.co",
    "name": "John Doe"
  },
  "acss_debit": {
    "email": "test@subbly.co",
    "name": "John Doe",
    "bank_name": "Royal Bank of Canada",
    "transit_number": "12345",
    "institution_number": "123",
    "last_four": "6789"
  },
  "us_bank_account": {
    "email": "test@subbly.co",
    "name": "John Doe",
    "bank_name": "US Bank",
    "last4": "6789",
    "routing_number": "123456789",
    "account_type": "checking",
    "account_holder_type": "individual"
  },
  "sepa_debit": {
    "email": "test@subbly.co",
    "name": "John Doe",
    "iban_last4": "6789",
    "bank_code": "123456",
    "country": "DE",
    "branch_code": "12345"
  },
  "sofort": {
    "email": "test@subbly.co",
    "name": "John Doe",
    "country": "DE"
  },
  "link": {
    "email": "test@subbly.co",
    "name": "John Doe"
  },
  "cashapp": {
    "email": "test@subbly.co",
    "name": "John Doe",
    "buyer_id": "cashapp:123456789",
    "cash_tag": "$subbly"
  },
  "created_at": "2022-04-01T00:00:00.000000Z"
}

Get payment method by ID

GET /payment_methods/{payment_method_id}

A detailed description of the payment method. expand[]: Accepted for consistency with other endpoints; the payment method has no expandable relations.

Path parameters

payment_method_idRequiredinteger

Payment method ID

Format: integer.

Query parameters

expand[]optionalstring[]

List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.

ReturnsPaymentMethod

Payment method object response

Error responses

400object

The payment method belongs to another shop.

404object

The payment method does not exist or has been deleted.

curl https://api.subbly.co/private/v1/payment_methods/{payment_method_id} \
  -H 'X-API-KEY: <api-key>'

Response

{
  "id": 567,
  "type": "card",
  "identifier": "4242",
  "currencies": [
    "USD",
    "EUR"
  ],
  "card": {
    "last_four": "4242",
    "expiry_month": "2",
    "expiry_year": "2099",
    "type": "credit",
    "brand": "visa"
  },
  "ideal": {
    "bank": "ING",
    "bic": "INGBNL2A",
    "email": "test@subbly.co",
    "name": "John Doe"
  },
  "bancontact": {
    "email": "test@subbly.co",
    "name": "John Doe"
  },
  "acss_debit": {
    "email": "test@subbly.co",
    "name": "John Doe",
    "bank_name": "Royal Bank of Canada",
    "transit_number": "12345",
    "institution_number": "123",
    "last_four": "6789"
  },
  "us_bank_account": {
    "email": "test@subbly.co",
    "name": "John Doe",
    "bank_name": "US Bank",
    "last4": "6789",
    "routing_number": "123456789",
    "account_type": "checking",
    "account_holder_type": "individual"
  },
  "sepa_debit": {
    "email": "test@subbly.co",
    "name": "John Doe",
    "iban_last4": "6789",
    "bank_code": "123456",
    "country": "DE",
    "branch_code": "12345"
  },
  "sofort": {
    "email": "test@subbly.co",
    "name": "John Doe",
    "country": "DE"
  },
  "link": {
    "email": "test@subbly.co",
    "name": "John Doe"
  },
  "cashapp": {
    "email": "test@subbly.co",
    "name": "John Doe",
    "buyer_id": "cashapp:123456789",
    "cash_tag": "$subbly"
  },
  "created_at": "2022-04-01T00:00:00.000000Z"
}

Delete a payment method

DELETE /payment_methods/{payment_method_id}

Remove a stored payment method and detach it at the gateway. When it was the customer's default payment method, the default is cleared as well. The payment method must belong to your shop.

Path parameters

payment_method_idRequiredinteger

Payment method ID

Format: integer.

ReturnsPaymentMethod

The deleted payment method

Error responses

404object

The payment method does not exist or belongs to another shop.

curl -X DELETE https://api.subbly.co/private/v1/payment_methods/{payment_method_id} \
  -H 'X-API-KEY: <api-key>'

Response

{
  "id": 567,
  "type": "card",
  "identifier": "4242",
  "currencies": [
    "USD",
    "EUR"
  ],
  "card": {
    "last_four": "4242",
    "expiry_month": "2",
    "expiry_year": "2099",
    "type": "credit",
    "brand": "visa"
  },
  "ideal": {
    "bank": "ING",
    "bic": "INGBNL2A",
    "email": "test@subbly.co",
    "name": "John Doe"
  },
  "bancontact": {
    "email": "test@subbly.co",
    "name": "John Doe"
  },
  "acss_debit": {
    "email": "test@subbly.co",
    "name": "John Doe",
    "bank_name": "Royal Bank of Canada",
    "transit_number": "12345",
    "institution_number": "123",
    "last_four": "6789"
  },
  "us_bank_account": {
    "email": "test@subbly.co",
    "name": "John Doe",
    "bank_name": "US Bank",
    "last4": "6789",
    "routing_number": "123456789",
    "account_type": "checking",
    "account_holder_type": "individual"
  },
  "sepa_debit": {
    "email": "test@subbly.co",
    "name": "John Doe",
    "iban_last4": "6789",
    "bank_code": "123456",
    "country": "DE",
    "branch_code": "12345"
  },
  "sofort": {
    "email": "test@subbly.co",
    "name": "John Doe",
    "country": "DE"
  },
  "link": {
    "email": "test@subbly.co",
    "name": "John Doe"
  },
  "cashapp": {
    "email": "test@subbly.co",
    "name": "John Doe",
    "buyer_id": "cashapp:123456789",
    "cash_tag": "$subbly"
  },
  "created_at": "2022-04-01T00:00:00.000000Z"
}