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

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

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-01 00:00:00",
    "updated_at": "2022-04-01 00:00:00"
  }
]

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

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-01 00:00:00",
  "updated_at": "2022-04-01 00:00:00"
}

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

403any

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

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-01 00:00:00",
  "updated_at": "2022-04-01 00:00:00"
}

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

403any

The payment method does not belong to the customer.

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-01 00:00:00",
  "updated_at": "2022-04-01 00:00:00"
}

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

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.

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-01 00:00:00",
    "updated_at": "2022-04-01 00:00:00"
  }
]

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.

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-01 00:00:00",
  "updated_at": "2022-04-01 00:00:00"
}

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

403any

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

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-01 00:00:00",
  "updated_at": "2022-04-01 00:00:00"
}

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

403any

The payment method does not belong to the customer.

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-01 00:00:00",
  "updated_at": "2022-04-01 00:00:00"
}