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.
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 |
Paths listed below and denoted with an asterisk are accessible to both User and Admin Roles.
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"
}
}
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"
}
}
]
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"
}
}
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. |
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. |
Changes since API version
2019-02-01
- Creating a Stripe payment method now needs two requests: 1)
POST /payment_methods
with 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 bypayment_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.
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"
}
}
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. Refer to Stripe’s docs for payment_methods/create and stripe-js 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"
}
}
Specific fields for a Vipps payment method object.
Attributes | Type | Description |
customer_number | string | Phone number of the customer. |
Parameters
HTTP
Attribute | Type | Description |
payment_method | string | Must be vipps for a Vipps payment method. |
customer_number | string | Phone number of the customer. |
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"
}
Last modified 2yr ago