billing - Documentation

# billing

## Bucket. billing

### Methods

#### (route) attachBankAccount(:id)

##### Route:

Method | Path
--- | ---
POST | /api/bucket/:id/payment/banks

Add a bank account to the bucket customer

##### Authentication

A authentication is needed to access this endpoint

##### Body Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
iban | String | optional | the iban used to recognize the account
type | String |  | the type of the bank account (currently only sepa is available)
name | String |  | name of the bank account owner

##### Header Parameters:

Name | Type | Description
--- | --- | ---
Authorization | String | bearer access token issued for the user

##### Route Parameters:

Name | Type | Description
--- | --- | ---
:id | String | bucket id

##### Response:

Name | Type | Description
--- | --- | ---
data | Object | stripe credit card Object

##### Response Code:

Type | Description
--- | ---
400 | missing parameters
500 | stripe error
200 | succesfully added the account

##### Parameters:

Name | Type | Description
--- | --- | ---
`:id` |  | bucket id

#### (async, route) attachCreditCard(:id)

##### Route:

Method | Path
--- | ---
POST | /api/bucket/:id/payment/cards

Add a credit card to the bucket customer

##### Authentication

A authentication is needed to access this endpoint

##### Body Parameters:

Name | Type | Description
--- | --- | ---
token | String | card token generated by stripe

##### Header Parameters:

Name | Type | Description
--- | --- | ---
Authorization | String | bearer access token issued for the user

##### Route Parameters:

Name | Type | Description
--- | --- | ---
:id | String | bucket id

##### Response:

Name | Type | Description
--- | --- | ---
data | Object | stripe credit card Object

##### Response Code:

Type | Description
--- | ---
400 | missing parameters
500 | stripe error
200 | succesfully added the card

##### Parameters:

Name | Type | Description
--- | --- | ---
`:id` |  | bucket id

#### (route) deleteBankAccount(:id)

##### Route:

Method | Path
--- | ---
DELETE | /api/bucket/:id/payment/banks

Delete the bank account connected to one bucket

##### Authentication

A authentication is needed to access this endpoint

##### Header Parameters:

Name | Type | Description
--- | --- | ---
Authorization | String | bearer access token issued for the user

##### Route Parameters:

Name | Type | Description
--- | --- | ---
:id | String | bucket id

##### Response:

Name | Type | Description
--- | --- | ---
. | Object | stripe source object

##### Response Code:

Type | Description
--- | ---
500 | stripe error
200 | succesfully retieved the card
404 | the user doesn't have any default account

##### Parameters:

Name | Type | Description
--- | --- | ---
`:id` |  | bucket id

#### (async, route) deleteCreditCard(:id, :card_id)

##### Route:

Method | Path
--- | ---
DELETE | /api/bucket/:id/payment/card/:card_id

Delete a specific credit card of the bucket customer

##### Authentication

A authentication is needed to access this endpoint

##### Header Parameters:

Name | Type | Description
--- | --- | ---
Authorization | String | bearer access token issued for the user

##### Route Parameters:

Name | Type | Description
--- | --- | ---
:id | String | bucket id
:card_id | String | the stripe id of the card

##### Response:

Name | Type | Description
--- | --- | ---
. | Object | stripe card object

##### Response Code:

Type | Description
--- | ---
500 | stripe error
400 | missing parameters card_id
200 | succesfully retieved the card
403 | the user must have one card active when having a subscription

##### Parameters:

Name | Type | Description
--- | --- | ---
`:id` |  | bucket id
`:card_id` |  | the stripe id of the card

#### (route) fetchBankAccount(:id)

##### Route:

Method | Path
--- | ---
GET | /api/bucket/:id/payment/banks

Fetch the bank account connected to a bucket

##### Authentication

A authentication is needed to access this endpoint

##### Header Parameters:

Name | Type | Description
--- | --- | ---
Authorization | String | bearer access token issued for the user

##### Route Parameters:

Name | Type | Description
--- | --- | ---
:id | String | bucket id

##### Response:

Name | Type | Description
--- | --- | ---
data | Object | stripe source object

##### Response Code:

Type | Description
--- | ---
500 | stripe error
404 | the user doesn't have any default account
200 | succesfully retieved the card

##### Parameters:

Name | Type | Description
--- | --- | ---
`:id` |  | bucket id

#### (route) fetchCreditCard(:id, :card_id)

##### Route:

Method | Path
--- | ---
GET | /api/bucket/:id/payment/card/:card_id

Fetch a specific credit card of the bucket customer

##### Authentication

A authentication is needed to access this endpoint

##### Header Parameters:

Name | Type | Description
--- | --- | ---
Authorization | String | bearer access token issued for the user

##### Route Parameters:

Name | Type | Description
--- | --- | ---
:id | String | bucket id
:card_id | String | the stripe id of the card

##### Response:

Name | Type | Description
--- | --- | ---
data | Array | stripe card object

##### Response Code:

Type | Description
--- | ---
500 | stripe error
400 | missing parameters card_id
404 | the user doesn't have any default card
200 | succesfully retieved the card

##### Parameters:

Name | Type | Description
--- | --- | ---
`:id` |  | bucket id
`:card_id` |  | the stripe id of the card

#### (route) fetchCreditCards(:id)

##### Route:

Method | Path
--- | ---
GET | /api/bucket/:id/payment/cards

List the credits card that the bucket customer have

##### Authentication

A authentication is needed to access this endpoint

##### Header Parameters:

Name | Type | Description
--- | --- | ---
Authorization | String | bearer access token issued for the user

##### Route Parameters:

Name | Type | Description
--- | --- | ---
:id | String | bucket id

##### Response:

Name | Type | Description
--- | --- | ---
data | Array | list of stripe cards object

##### Response Code:

Type | Description
--- | ---
500 | stripe error
404 | the user doesn't have any default card
200 | succesfully retieved the charges

##### Parameters:

Name | Type | Description
--- | --- | ---
`:id` |  | bucket id

#### (async, route) fetchDefaultCreditCard(:id)

##### Route:

Method | Path
--- | ---
GET | /api/bucket/:id/payment/card

Fetch the default credit card of the bucket customer

##### Authentication

A authentication is needed to access this endpoint

##### Header Parameters:

Name | Type | Description
--- | --- | ---
Authorization | String | bearer access token issued for the user

##### Route Parameters:

Name | Type | Description
--- | --- | ---
:id | String | bucket id

##### Response:

Name | Type | Description
--- | --- | ---
data | Array | stripe card object

##### Response Code:

Type | Description
--- | ---
500 | stripe error
404 | the user doesn't have any default card
200 | succesfully retieved the card

##### Parameters:

Name | Type | Description
--- | --- | ---
`:id` |  | bucket id

#### (route) fetchMetadata(:id)

##### Route:

Method | Path
--- | ---
GET | /api/bucket/:id/payment

Fetch stripe metadata for a bucket customer

##### Authentication

A authentication is needed to access this endpoint

##### Header Parameters:

Name | Type | Description
--- | --- | ---
Authorization | String | bearer access token issued for the user

##### Route Parameters:

Name | Type | Description
--- | --- | ---
:id | String | bucket id

##### Response:

Name | Type | Description
--- | --- | ---
. | Object | stripe metadata object

##### Response Code:

Type | Description
--- | ---
500 | stripe error
400 | missing parameters card_id
200 | succesfully retrieved the metadata

##### Parameters:

Name | Type | Description
--- | --- | ---
`:id` |  | bucket id

#### (route) getInvoices(:id)

##### Route:

Method | Path
--- | ---
GET | /api/bucket/:id/payment/invoices

Retrieve the invoices for a given bucket

##### Authentication

A authentication is needed to access this endpoint

##### Header Parameters:

Name | Type | Description
--- | --- | ---
Authorization | String | bearer access token issued for the user

##### Route Parameters:

Name | Type | Description
--- | --- | ---
:id | String | bucket id

##### Response:

Name | Type | Description
--- | --- | ---
. | Array | array of invoices

##### Response Code:

Type | Description
--- | ---
400 | Missing/invalid parameters
404 | This bucket hasn't invoices
200 | succesfully returns invoices

##### Parameters:

Name | Type | Description
--- | --- | ---
`:id` |  | bucket id

#### (route) getReceipts(:id)

##### Route:

Method | Path
--- | ---
GET | /api/bucket/:id/payment/receipts

Retrieve the receipts for a given bucket

##### Authentication

A authentication is needed to access this endpoint

##### Header Parameters:

Name | Type | Description
--- | --- | ---
Authorization | String | bearer access token issued for the user

##### Route Parameters:

Name | Type | Description
--- | --- | ---
:id | String | bucket id

##### Response:

Name | Type | Description
--- | --- | ---
. | Array | array of receipts

##### Response Code:

Type | Description
--- | ---
400 | Missing/invalid parameters
404 | This bucket hasn't receipts
200 | succesfully returns receipts

##### Parameters:

Name | Type | Description
--- | --- | ---
`:id` |  | bucket id

#### (route) getSubcription(:id)

##### Route:

Method | Path
--- | ---
GET | /api/bucket/:id/payment/subscription

Retrieve the subscription for the bucket

##### Authentication

A authentication is needed to access this endpoint

##### Header Parameters:

Name | Type | Description
--- | --- | ---
Authorization | String | bearer access token issued for the user

##### Route Parameters:

Name | Type | Description
--- | --- | ---
:id | String | bucket id

##### Response:

Name | Type | Description
--- | --- | ---
. | Object | subscription object

##### Response Code:

Type | Description
--- | ---
404 | the bucket doesnt have any subscription
500 | database error
200 | succesfully retrieved the subscription

##### Parameters:

Name | Type | Description
--- | --- | ---
`:id` |  | bucket id

#### (async, route) getSubcriptionState(:id)

##### Route:

Method | Path
--- | ---
GET | /api/bucket/:id/payment/subscription/state

Retrieve the state of the subscription (current or past)

##### Authentication

A authentication is needed to access this endpoint

##### Header Parameters:

Name | Type | Description
--- | --- | ---
Authorization | String | bearer access token issued for the user

##### Route Parameters:

Name | Type | Description
--- | --- | ---
:id | String | bucket id

##### Response:

Name | Type | Description
--- | --- | ---
status | String | stripe state of the subscription
plan | String | stripe plan name of the subscription
canceled_at | String | if he sub has been cancelled, add the date

##### Response Code:

Type | Description
--- | ---
404 | the bucket doesnt have any subscription
500 | database error
200 | succesfully retrieved the subscription

##### Parameters:

Name | Type | Description
--- | --- | ---
`:id` |  | bucket id

#### (async, route) paymentIntentSucceed(:id, :paymentIntent)

##### Route:

Method | Path
--- | ---
POST | /api/bucket/:id/payment/subscribe/:paymentIntent

Call when payment intent succeeded (after 3D secure)

##### Authentication

A authentication is needed to access this endpoint

##### Body Parameters:

Name | Type | Description
--- | --- | ---
plan | String | name of the plan to upgrade to

##### Header Parameters:

Name | Type | Description
--- | --- | ---
Authorization | String | bearer access token issued for the user

##### Route Parameters:

Name | Type | Description
--- | --- | ---
:id | String | bucket id
:paymentIntent | String | paymentIntent id

##### Response:

Name | Type | Description
--- | --- | ---
bucket | Object | the bucket object

##### Response Code:

Type | Description
--- | ---
400 | missing/invalid parameters
500 | stripe/database error
200 | succesfully upgraded

##### Parameters:

Name | Type | Description
--- | --- | ---
`:id` |  | bucket id
`:paymentIntent` |  | paymentIntent id

#### (async, route) setDefaultCard(:id, :card_id)

##### Route:

Method | Path
--- | ---
POST | /api/bucket/:id/payment/card/:card_id/default

Set a specific credit card as the bucket customer default card

##### Authentication

A authentication is needed to access this endpoint

##### Header Parameters:

Name | Type | Description
--- | --- | ---
Authorization | String | bearer access token issued for the user

##### Route Parameters:

Name | Type | Description
--- | --- | ---
:id | String | bucket id
:card_id | String | the stripe id of the card

##### Response:

Name | Type | Description
--- | --- | ---
data | Object | stripe card object

##### Response Code:

Type | Description
--- | ---
500 | stripe error
400 | missing parameters card_id
200 | succesfully set the card as default

##### Parameters:

Name | Type | Description
--- | --- | ---
`:id` |  | bucket id
`:card_id` |  | the stripe id of the card

#### (async, route) startTrial(:id)

##### Route:

Method | Path
--- | ---
PUT | /api/bucket/:id/payment/trial

Launch a trial for the bucket

##### Authentication

A authentication is needed to access this endpoint

##### Body Parameters:

Name | Type | Description
--- | --- | ---
plan | String | Plan to trial

##### Header Parameters:

Name | Type | Description
--- | --- | ---
Authorization | String | bearer access token issued for the user

##### Route Parameters:

Name | Type | Description
--- | --- | ---
:id | String | bucket id

##### Response:

Name | Type | Description
--- | --- | ---
duration | String | the duration of the trial
plan | String | the plan of the trial

##### Response Code:

Type | Description
--- | ---
400 | can't claim trial
200 | trial launched

##### Parameters:

Name | Type | Description
--- | --- | ---
`:id` |  | bucket id

#### (async, route) subscribe(:id)

##### Route:

Method | Path
--- | ---
POST | /api/bucket/:id/payment/subscribe

Subscribe to a plan

##### Authentication

A authentication is needed to access this endpoint

##### Body Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
plan | String |  | name of the plan to upgrade to
stripe_token | String | optional | a card token created by stripe
coupon_id | String | optional | the id of the stripe coupon

##### Header Parameters:

Name | Type | Description
--- | --- | ---
Authorization | String | bearer access token issued for the user

##### Route Parameters:

Name | Type | Description
--- | --- | ---
:id | String | bucket id

##### Response:

Name | Type | Description
--- | --- | ---
bucket | Object | the bucket object
subscription | Object | the subscription object attached to the subscription

##### Response Code:

Type | Description
--- | ---
400 | missing/invalid parameters
403 | need a credit card OR not allowed to subscribe to the plan
500 | stripe/database error
200 | succesfully upgraded

##### Parameters:

Name | Type | Description
--- | --- | ---
`:id` |  | bucket id

#### (route) updateCreditCard(:id)

##### Route:

Method | Path
--- | ---
PUT | /api/bucket/:id/payment/card

Update a credit card of the bucket customer

##### Authentication

A authentication is needed to access this endpoint

##### Body Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
id | String |  | stripe card id
address_line1 | String | optional |
address_country | String | optional |
address_zip | String | optional |
address_city | String | optional |

##### Header Parameters:

Name | Type | Description
--- | --- | ---
Authorization | String | bearer access token issued for the user

##### Route Parameters:

Name | Type | Description
--- | --- | ---
:id | String | bucket id

##### Response:

Name | Type | Description
--- | --- | ---
data | Array | stripe card object

##### Response Code:

Type | Description
--- | ---
500 | stripe error
400 | missing parameters, you need to specify a card
200 | succesfully updated the card

##### Parameters:

Name | Type | Description
--- | --- | ---
`:id` |  | bucket id

#### (async, route) updateMetadata(:id)

##### Route:

Method | Path
--- | ---
PUT | /api/bucket/:id/payment

Update a stripe metadata of the bucket customer

##### Authentication

A authentication is needed to access this endpoint

##### Body Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
metadata | Object |  | the metadata you can update
metadata.vat_number | String | optional |
metadata.company_name | String | optional |
metadata.receipt_email | String | optional |

##### Header Parameters:

Name | Type | Description
--- | --- | ---
Authorization | String | bearer access token issued for the user

##### Route Parameters:

Name | Type | Description
--- | --- | ---
:id | String | bucket id

##### Response:

Name | Type | Description
--- | --- | ---
data | Array | stripe customer metadata object

##### Response Code:

Type | Description
--- | ---
500 | stripe error
400 | missing parameters, you need to specify a card
200 | succesfully updated the card

##### Parameters:

Name | Type | Description
--- | --- | ---
`:id` |  | bucket id