Payment Methods

To pay for things, your users need to have a payment method in the system.  They can add it in their purchasing flow, or have it on file as their default_payment_method , which can be updated in the User Object. The default_payment_method will automatically be set to the last payment method used by the user to pay for an order.
Note: Ensure you update the BuiltOn API when you users add or update a payment method. When done directly through Stripe, our APIs won’t be notified and the payment will not be processed or tracked in our system.
Payment Method Object
Attributes
Type
Description
method
string
Currently just  stripe, but more options coming soon.
name
string
Name of the Payment Method. This can be set by the user and/or shown if desired.
user
object
​User associated with Payment Method.
Paths listed below and denoted with a star are accessible to both User and Admin Roles.
Retrieve a Payment Method*
Retrieves the payment method with a given ID.
Parameters
Request
Response
​
​
​
payment_method_id
string
This is the unique ID of the queried payment method.
GET /payment_methods/<payment_method_id> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
​
{
  "company": {
    "$oid": "57ee9c71d76d431f8511142f"
  },
  "created": {
    "$date": 1476118043580
  },
  "_id": {
    "$oid": "<payment-method-id>"
  },
  "modified": {
    "$date": 1476118043580
  },
  "deleted": false,
  "active": true,
  "user": {
    "$oid": "57ee9c72d76d431f85111432"
  },
  "method": "stripe",
  "name": "Stripe",
  "customer_id": "cus_CJjTlT4Wci2P0u",
  "source": "pm_1EzglsEeeXxFpLJtjuEvd123",
  "card": {
    "object": "card",
    "address_state": null,
    "fingerprint": "npPw68vQg1usKUWb",
    "metadata": {},
    "exp_year": 2019,
    "country": "US",
    "last4": "4242",
    "address_zip_check": null,
    "address_zip": null,
    "funding": "credit",
    "cvc_check": "unchecked",
    "id": "card_1Bv5yfEeeXxFpLJtPBVfQ1wZ",
    "tokenization_method": null,
    "address_line1": null,
    "exp_month": 12,
    "brand": "Visa",
    "dynamic_last4": null,
    "address_country": null,
    "address_line2": null,
    "address_line1_check": null,
    "name": null,
    "address_city": null
  },
  "setup_intent": {
    "id": "seti_SripeSetupIntentID",
    "client_secret": "seti_StripeSecret",
    "status": "succeeded"
  }
}
List all Payment Methods*
Retrieves a list of all Payment Methods associated with the user.
Parameters
Request
Response
Attribute
Type
Description
size
number
Number of items to retrieve.
page
number
Which page to retrieve. Default page size is 10.
sort
string
Field used for sorting results.
GET /payment_methods HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
​
[
  {
    "company": {
      "$oid": "57ee9c71d76d431f8511142f"
    },
    "created": {
      "$date": 1476118043580
    },
    "_id": {
      "$oid": "<payment-method-id>"
    },
    "modified": {
      "$date": 1476118043580
    },
    "deleted": false,
    "active": true,
    "user": {
      "$oid": "57ee9c72d76d431f85111432"
    },
    "method": "stripe",
    "name": "Stripe",
    "customer_id": "cus_CJjTlT4Wci2P0u",
    "source": "pm_1EzglsEeeXxFpLJtjuEvd123",
    "card": {
      "object": "card",
      "address_state": null,
      "fingerprint": "npPw68vQg1usKUWb",
      "metadata": {},
      "exp_year": 2019,
      "country": "US",
      "last4": "4242",
      "address_zip_check": null,
      "address_zip": null,
      "funding": "credit",
      "cvc_check": "unchecked",
      "id": "card_1Bv5yfEeeXxFpLJtPBVfQ1wZ",
      "tokenization_method": null,
      "address_line1": null,
      "exp_month": 12,
      "brand": "Visa",
      "dynamic_last4": null,
      "address_country": null,
      "address_line2": null,
      "address_line1_check": null,
      "name": null,
      "address_city": null
    },
    "setup_intent": {
      "id": "seti_SripeSetupIntentID",
      "client_secret": "seti_StripeSecret",
      "status": "succeeded"
    }
  }
]
Delete Payment Method*
Parameters
Request
Response
Argument
Type
Description
payment_method_id
string
This is the unique ID of the payment method.
DELETE /payment_methods/<payment_method_id> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
​
{
  "company": {
    "$oid": "57ee9c71d76d431f8511142f"
  },
  "created": {
    "$date": 1476118043580
  },
  "_id": {
    "$oid": "<payment-method-id>"
  },
  "modified": {
    "$date": 1476118043580
  },
  "deleted": true,
  "active": false,
  "user": {
    "$oid": "57ee9c72d76d431f85111432"
  },
  "method": "stripe",
  "name": "Stripe",
  "customer_id": "cus_CJjTlT4Wci2P0u",
  "source": "pm_1EzglsEeeXxFpLJtjuEvd123",
  "card": {
    "object": "card",
    "address_state": null,
    "fingerprint": "npPw68vQg1usKUWb",
    "metadata": {},
    "exp_year": 2019,
    "country": "US",
    "last4": "4242",
    "address_zip_check": null,
    "address_zip": null,
    "funding": "credit",
    "cvc_check": "unchecked",
    "id": "card_1Bv5yfEeeXxFpLJtPBVfQ1wZ",
    "tokenization_method": null,
    "address_line1": null,
    "exp_month": 12,
    "brand": "Visa",
    "dynamic_last4": null,
    "address_country": null,
    "address_line2": null,
    "address_line1_check": null,
    "name": null,
    "address_city": null
  },
  "setup_intent": {
    "id": "seti_SripeSetupIntentID",
    "client_secret": "seti_StripeSecret",
    "status": "succeeded"
  }
}
Stripe Payment Method
Stripe Object
Attributes
Type
Description
source
string
Contains payment method id from Stripe
card
object
Card's details. e.q: last4 numbers, expiration year, etc. 
setup_intent
object
A Setup Intent object
Setup Intent Object
Attributes
Type
Description
id
string
The Setup Intent from the Payment Method provider 
client_secret
string
The client secret key from the Payment method provider, helps to validate the creation off a Payment Method.
status 
string
The status of the Setup Intent, could be : succeeded, require_payment_method, etc.
Create Payment Method*
Changes since API version 2019-02-01
2019-07-31 - Stripe SetupIntent object
Creating a Stripe payment method needs two requests now:
1)POST /payment_methodswith payment_method to ask for an Setup Intent ID
2)PUT /payment_methods to update the Payment Method with the Stripe payment method, e.q: pm_D1as56d14a6
2019-07-24 - SCA Changes
token has been replaced by payment_method_id
Until the 14th of September 2019, you can still use the APIs as you've used so far but, after this date if you keep using the old Stripe Tokens to do your payments, you'll be getting errors from the Banks requiring further authentication and you'll have to upgrade your APIs accordingly to use the new Payment Intent APIs.
Go to our SCA section to read more.
Ask for a Setup Intent ID
This request will return you an empty Payment Method object except for a SetupIntent object, where you will find 3 important fields: id, client_secret and, status. On your client you will need both the id and client_secret to generate a Stripe payment method, using the Stripe SDK.
Parameters
Request
Response
Attribute
Type
Description
payment_method
string
Must be stripe for a Stripe payment method.
POST /payment_methods HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
​
{
  "payment_method": "stripe"
}
HTTP/1.1 200 OK
Content-Type: application/json
​
{
  "company": {
    "$oid": "57ee9c71d76d431f8511142f"
  },
  "created": {
    "$date": 1476118043580
  },
  "_id": {
    "$oid": "<payment-method-id>"
  },
  "modified": {
    "$date": 1476118043580
  },
  "deleted": false,
  "active": true,
  "user": {
    "$oid": "57ee9c72d76d431f85111432"
  },
  "method": "stripe",
  "name": "Stripe",
  "customer_id": "cus_CJjTlT4Wci2P0u",
  "source": "",
  "card": { },
  "setup_intent": {
    "id": "seti_SripeSetupIntentID",
    "client_secret": "seti_StripeSecret",
    "status": "requires_payment_method"
  }
}
Update the Payment Method
After you created a Stripe payment method, you will be able to update the current user's payment method with the Stripe payment method Id.
Parameter
Request
Response
Attribute
Type
Description
payment_method_id
string
Stripe payment method id. Response will contain non-sensitive user card details 
Stripe references:
​https://stripe.com/docs/api/payment_methods/create​
​https://stripe.com/docs/stripe-js/reference#stripe-create-payment-method​
PUT /payment_methods/<payment_method_id> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
​
{
  "payment_method_id": "pm_1EzglsEeeXxFpLJtjuEvd123"
}
HTTP/1.1 200 OK
Content-Type: application/json
​
{
  "company": {
    "$oid": "57ee9c71d76d431f8511142f"
  },
  "created": {
    "$date": 1476118043580
  },
  "_id": {
    "$oid": "<payment-method-id>"
  },
  "modified": {
    "$date": 1476118043580
  },
  "deleted": false,
  "active": true,
  "user": {
    "$oid": "57ee9c72d76d431f85111432"
  },
  "method": "stripe",
  "name": "Stripe",
  "customer_id": "cus_CJjTlT4Wci2P0u",
  "source": "pm_1EzglsEeeXxFpLJtjuEvd123",
  "card": {
    "object": "card",
    "address_state": null,
    "fingerprint": "npPw68vQg1usKUWb",
    "metadata": {},
    "exp_year": 2019,
    "country": "US",
    "last4": "4242",
    "address_zip_check": null,
    "address_zip": null,
    "funding": "credit",
    "cvc_check": "unchecked",
    "id": "card_1Bv5yfEeeXxFpLJtPBVfQ1wZ",
    "tokenization_method": null,
    "address_line1": null,
    "exp_month": 12,
    "brand": "Visa",
    "dynamic_last4": null,
    "address_country": null,
    "address_line2": null,
    "address_line1_check": null,
    "name": null,
    "address_city": null
  },
  "setup_intent": {
    "id": "seti_SripeSetupIntentID",
    "client_secret": "seti_StripeSecret",
    "status": "succeeded"
  }
}
​
*Paths listed above and denoted with a star are accessible to both Users and Admins.

Setup a Payment Provider

Strong Customer Authentication

Last updated -2

Attributes	Type	Description
`method`	`string`	Currently just `stripe`, but more options coming soon.
`name`	`string`	Name of the Payment Method. This can be set by the user and/or shown if desired.
`user`	`object`	`User` associated with Payment Method.

Attributes	Type	Description
`source`	`string`	Contains payment method id from Stripe
`card`	`object`	Card's details. e.q: last4 numbers, expiration year, etc.
`setup_intent`	`object`	A `Setup Intent` object

Attributes	Type	Description
`id`	`string`	The Setup Intent from the Payment Method provider
`client_secret`	`string`	The client secret key from the Payment method provider, helps to validate the creation off a Payment Method.
`status`	`string`	The status of the Setup Intent, could be : `succeeded`, `require_payment_method`, etc.


`payment_method_id`	`string`	This is the unique ID of the queried payment method.

Attribute	Type	Description
`size`	`number`	Number of items to retrieve.
`page`	`number`	Which page to retrieve. Default page size is 10.
`sort`	`string`	Field used for sorting results.

Argument	Type	Description
`payment_method_id`	`string`	This is the unique ID of the payment method.