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

payment_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.

Create a Stripe Payment Method*

Parameters
Request
Response

Attribute

Type

Description

payment_method

string

Must be stripe for a Stripe payment method.

token

string

Token created with the card details (number, expiration month, expiration year, cvc).

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",
"token": "tok_1Bv5yfEeeXxFpLJtpWYeGYuy"
}
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,
"user": {
"$oid": "57ee9c72d76d431f85111432"
},
"method": "stripe",
"name": "Stripe",
"customer_id": "cus_CJjTlT4Wci2P0u",
"token": "tok_1Bv5yfEeeXxFpLJtpWYeGYuy",
"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
}
}

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
{
"masked_card_number":"XXXXXXXXXXXX1234",
"merchant":"some_merchant_id",
"user":{
"$oid":"57ee9c72d76d431f85111432"
},
"deleted":false,
"method":"dibs",
"company":{
"$oid":"57ee9c71d76d431f8511142f"
},
"created":{
"$date":1475254021326
},
"ticket":"some_ticket_id",
"modified":{
"$date":1475254021326
},
"active":true,
"_id":{
"$oid":"<payment_method_id>"
}
}

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
[
{
"masked_card_number":"XXXXXXXXXXXX1234",
"merchant":"some_merchant_id",
"user":{
"$oid":"57ee9c72d76d431f85111432"
},
"deleted":false,
"method":"dibs",
"company":{
"$oid":"57ee9c71d76d431f8511142f"
},
"created":{
"$date":1475254021326
},
"ticket":"some_ticket_id",
"modified":{
"$date":1475254021326
},
"active":true,
"_id":{
"$oid":"<payment-method-id>"
}
}
]

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
[
{
"masked_card_number":"XXXXXXXXXXXX1234",
"merchant":"some_merchant_id",
"user":{
"$oid":"57ee9c72d76d431f85111432"
},
"deleted":true,
"method":"dibs",
"company":{
"$oid":"57ee9c71d76d431f8511142f"
},
"created":{
"$date":1475254021326
},
"ticket":"some_ticket_id",
"modified":{
"$date":1475254021326
},
"active":false,
"_id":{
"$oid":"<payment-method-id>"
}
}
]

*Paths listed above and denoted with a star are accessible to both Users and Admins.