Storefront API reference

Wallet

Storefront Wallet API endpoints

Endpoints

POST/wallet/setup
GET/wallet
POST/wallet
DELETE/wallet/{payment_method_id}
POST/wallet/{payment_method_id}/default

Store payment method

POST /wallet/setup

An API endpoint to setup token for payment method.

Request body

Setup payment method body

gateway_idoptionalinteger

ReturnsPaymentMethodSetup

Token required to setup payment method

tokenstring

Error responses

400object

The gateway is an Authorize.Net gateway, which has no setup flow.

422object

gateway_id is missing or is not a gateway of the shop.

curl -X POST https://api.subbly.co/storefront/v1/wallet/setup \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "gateway_id": 1
}'

Response

{
  "token": "set_1MPlVBH02BHbI05_secret_NA5gM6sNiJUdZJHjncpp1"
}

Get list of payment methods

GET /wallet

An API endpoint to get list of payment methods.

Query parameters

currency_codeoptionalstring

Currency ISO code

ReturnsPaymentMethod[]

Payment method object response

Error responses

401object

Missing or invalid customer token.

422object

currency_code is not a string, or expand is not an array of strings.

curl https://api.subbly.co/storefront/v1/wallet \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>'

Response

[
  {
    "id": 567,
    "type": "card",
    "identifier": "4242",
    "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",
      "last_four": "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",
    "updated_at": "2022-04-01T00:00:00.000000Z"
  }
]

Store payment method

POST /wallet

An API endpoint to store payment method.

Request body

Store payment method body

gateway_idRequiredinteger

tokenRequiredstring

ReturnsPaymentMethod

Payment method object response

Error responses

401object

Missing or invalid customer token.

422object

gateway_id is missing or is not a gateway of the shop, or token is missing or not a string.

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

Response

{
  "id": 567,
  "type": "card",
  "identifier": "4242",
  "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",
    "last_four": "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",
  "updated_at": "2022-04-01T00:00:00.000000Z"
}

Delete payment method

DELETE /wallet/{payment_method_id}

An API endpoint to delete a customer payment method. The payment method is also detached on the payment gateway.

The last remaining payment method can only be deleted when the shop allows it and the customer has no active subscription, otherwise the request is rejected.

Path parameters

payment_method_idRequiredinteger

Payment method ID

ReturnsPaymentMethod

The deleted payment method object

Error responses

400object

The payment method does not belong to the customer, or it is the last one left and cannot be removed.

401object

Missing or invalid customer token.

404object

The payment method does not exist or has already been deleted.

curl -X DELETE https://api.subbly.co/storefront/v1/wallet/{payment_method_id} \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>'

Response

{
  "id": 567,
  "type": "card",
  "identifier": "4242",
  "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",
    "last_four": "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",
  "updated_at": "2022-04-01T00:00:00.000000Z"
}

Set default payment method

POST /wallet/{payment_method_id}/default

An API endpoint to make a payment method the customer default one.

Path parameters

payment_method_idRequiredinteger

Payment method ID

ReturnsPaymentMethod

Payment method object response

Error responses

400object

The payment method does not belong to the customer.

401object

Missing or invalid customer token.

404object

The payment method does not exist.

422any

The payment method cannot be made the default: it belongs to a test mode gateway, or it is a card that has expired.

curl -X POST https://api.subbly.co/storefront/v1/wallet/{payment_method_id}/default \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>'

Response

{
  "id": 567,
  "type": "card",
  "identifier": "4242",
  "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",
    "last_four": "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",
  "updated_at": "2022-04-01T00:00:00.000000Z"
}

Wallet

Storefront Wallet API endpoints

Endpoints

POST/wallet/setup
GET/wallet
POST/wallet
DELETE/wallet/{payment_method_id}
POST/wallet/{payment_method_id}/default

Store payment method

POST /wallet/setup

An API endpoint to setup token for payment method.

Request body

Setup payment method body

gateway_idoptionalinteger

ReturnsPaymentMethodSetup

Token required to setup payment method

tokenstring

Error responses

400object

The gateway is an Authorize.Net gateway, which has no setup flow.

422object

gateway_id is missing or is not a gateway of the shop.

curl -X POST https://api.subbly.co/storefront/v1/wallet/setup \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "gateway_id": 1
}'

Response

{
  "token": "set_1MPlVBH02BHbI05_secret_NA5gM6sNiJUdZJHjncpp1"
}

Get list of payment methods

GET /wallet

An API endpoint to get list of payment methods.

Query parameters

currency_codeoptionalstring

Currency ISO code

ReturnsPaymentMethod[]

Payment method object response

idinteger

typestring

Possible values: paypal, card, ideal, sofort, bancontact, sepa_debit, acss_debit, us_bank_account, link, cashapp, amazon_pay.

identifierstring | null

cardobject | null

Only applicable for the card type

idealobject | null

Only applicable for the ideal type

bancontactobject | null

Only applicable for the bancontact type

acss_debitobject | null

Only applicable for the acss_debit type

us_bank_accountobject | null

Only applicable for the us_bank_account type

sepa_debitobject | null

Only applicable for the sepa_debit type

sofortobject | null

Only applicable for the sofort type

linkobject | null

Only applicable for the link type

cashappobject | null

Only applicable for the cashapp type

created_atstring | null

Format: date-time.

updated_atstring | null

Format: date-time.

Error responses

401object

Missing or invalid customer token.

422object

currency_code is not a string, or expand is not an array of strings.

curl https://api.subbly.co/storefront/v1/wallet \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>'

Response

[
  {
    "id": 567,
    "type": "card",
    "identifier": "4242",
    "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",
      "last_four": "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",
    "updated_at": "2022-04-01T00:00:00.000000Z"
  }
]

Store payment method

POST /wallet

An API endpoint to store payment method.

Request body

Store payment method body

gateway_idRequiredinteger

tokenRequiredstring

ReturnsPaymentMethod

Payment method object response

idinteger

typestring

Possible values: paypal, card, ideal, sofort, bancontact, sepa_debit, acss_debit, us_bank_account, link, cashapp, amazon_pay.

identifierstring | null

cardobject | null

Only applicable for the card type

idealobject | null

Only applicable for the ideal type

bancontactobject | null

Only applicable for the bancontact type

acss_debitobject | null

Only applicable for the acss_debit type

us_bank_accountobject | null

Only applicable for the us_bank_account type

sepa_debitobject | null

Only applicable for the sepa_debit type

sofortobject | null

Only applicable for the sofort type

linkobject | null

Only applicable for the link type

cashappobject | null

Only applicable for the cashapp type

created_atstring | null

Format: date-time.

updated_atstring | null

Format: date-time.

Error responses

401object

Missing or invalid customer token.

422object

gateway_id is missing or is not a gateway of the shop, or token is missing or not a string.

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

Response

{
  "id": 567,
  "type": "card",
  "identifier": "4242",
  "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",
    "last_four": "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",
  "updated_at": "2022-04-01T00:00:00.000000Z"
}

Delete payment method

DELETE /wallet/{payment_method_id}

An API endpoint to delete a customer payment method. The payment method is also detached on the payment gateway.

The last remaining payment method can only be deleted when the shop allows it and the customer has no active subscription, otherwise the request is rejected.

Path parameters

payment_method_idRequiredinteger

Payment method ID

ReturnsPaymentMethod

The deleted payment method object

idinteger

typestring

Possible values: paypal, card, ideal, sofort, bancontact, sepa_debit, acss_debit, us_bank_account, link, cashapp, amazon_pay.

identifierstring | null

cardobject | null

Only applicable for the card type

idealobject | null

Only applicable for the ideal type

bancontactobject | null

Only applicable for the bancontact type

acss_debitobject | null

Only applicable for the acss_debit type

us_bank_accountobject | null

Only applicable for the us_bank_account type

sepa_debitobject | null

Only applicable for the sepa_debit type

sofortobject | null

Only applicable for the sofort type

linkobject | null

Only applicable for the link type

cashappobject | null

Only applicable for the cashapp type

created_atstring | null

Format: date-time.

updated_atstring | null

Format: date-time.

Error responses

400object

The payment method does not belong to the customer, or it is the last one left and cannot be removed.

401object

Missing or invalid customer token.

404object

The payment method does not exist or has already been deleted.

curl -X DELETE https://api.subbly.co/storefront/v1/wallet/{payment_method_id} \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>'

Response

{
  "id": 567,
  "type": "card",
  "identifier": "4242",
  "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",
    "last_four": "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",
  "updated_at": "2022-04-01T00:00:00.000000Z"
}

Set default payment method

POST /wallet/{payment_method_id}/default

An API endpoint to make a payment method the customer default one.

Path parameters

payment_method_idRequiredinteger

Payment method ID

ReturnsPaymentMethod

Payment method object response

idinteger

typestring

Possible values: paypal, card, ideal, sofort, bancontact, sepa_debit, acss_debit, us_bank_account, link, cashapp, amazon_pay.

identifierstring | null

cardobject | null

Only applicable for the card type

idealobject | null

Only applicable for the ideal type

bancontactobject | null

Only applicable for the bancontact type

acss_debitobject | null

Only applicable for the acss_debit type

us_bank_accountobject | null

Only applicable for the us_bank_account type

sepa_debitobject | null

Only applicable for the sepa_debit type

sofortobject | null

Only applicable for the sofort type

linkobject | null

Only applicable for the link type

cashappobject | null

Only applicable for the cashapp type

created_atstring | null

Format: date-time.

updated_atstring | null

Format: date-time.

Error responses

400object

The payment method does not belong to the customer.

401object

Missing or invalid customer token.

404object

The payment method does not exist.

422any

The payment method cannot be made the default: it belongs to a test mode gateway, or it is a card that has expired.

curl -X POST https://api.subbly.co/storefront/v1/wallet/{payment_method_id}/default \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>'

Response

{
  "id": 567,
  "type": "card",
  "identifier": "4242",
  "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",
    "last_four": "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",
  "updated_at": "2022-04-01T00:00:00.000000Z"
}