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 your users add or update a payment method. When done directly through outside payment providers, 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 and vipps, 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 an asterisk are accessible to both User and Admin Roles.

Retrieve a Payment Method*

Retrieves the payment method with a given ID.

Parameters
Request
Response
Parameters

payment_method_id

string

This is the unique ID of the queried payment method.

Request
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
Response
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
Parameters

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.

Request
GET /payment_methods HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response
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
Parameters

Argument

Type

Description

payment_method_id

string

This is the unique ID of the payment method.

Request
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
Response
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.g: last 4 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 of a payment method.

status

string

The status of the Setup Intent. e.g.: succeeded, require_payment_method, etc.

Create Stripe Payment Method*

Changes since API version 2019-02-01

2019-07-31 - Stripe SetupIntent object

  • Creating a Stripe payment method now needs two requests: 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.g.: 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. 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
Parameters

Attribute

Type

Description

payment_method

string

Must be stripe for a Stripe payment method.

Request
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"
}
Response
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
Parameter

Attribute

Type

Description

payment_method_id

string

Stripe payment method id. Response will contain non sensitive user card details. Refer to Stripe’s docs for payment_methods/create and stripe-js create payment method

Request
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"
}
Response
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"
}
}

Vipps Payment Method

Vipps Object

Specific fields for a Vipps payment method object.

Attributes

Type

Description

customer_number

string

Phone number of the customer.

Create Vipps Payment Method

Parameters
HTTP
Parameters

Attribute

Type

Description

payment_method

string

Must be vipps for a Vipps payment method.

customer_number

string

Phone number of the customer.

HTTP
Request --
GET https://api.builton.dev/orders/<order_id>?expand=user HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt -or- service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"payment_method": "vipps",
"customer_number": "+47 424 42 424"
}
Response --
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": "vipps",
"name": "vipps",
"customer_number": "+47 424 42 424"
}