Payments

Your Users can pay for Orders and Subscriptions. But they'll need a Payment Method.

When you want to pay, you need to use the Payment object. Together with a Payment Method, among other fields, you’ll be able to create and process payments, as well as list all available payments.

Payment Object

Base
Stripe
Vipps
Base

Attributes

Type

Description

user

object

The user associated with the Payment.

amount

number

Amount as a Float with decimal points. Example: 10.23 USD

currency

string

3 letter ISO currency code as defined by ISO 4217.

human_id

string

Human readable ID. 6 characters long.

subject

string

Order or Subscription ID.

current_state

string

Current state of payment. Can be: created, processing, captured, succeeded, failed and cancelled.

active

boolean

Default is True.

payment_date

object

Date for scheduling payment,timestamp format.

payment_method

string

ID of existing Payment Method.

billing_address

object

The Address object with billing details, for use if supported by payment provider.

description

string

Some additional description, if desired and supported by payment provider.

metadata

array

Additional information on the payment, if supported by payment provider.

status_code

string

If the payment fails, this will have some code from the chosen payment method backend.

error_message

string

If the payment fails, this will have text describing the reason.

Stripe

Additional Payment attributes

Attributes

Type

Description

metadata.payment_intent.id

string

The Stripe PaymentIntent ID.

metadata.intent_client_secret

string

The Stripe PaymentIntent secret for re-authentication.

You will get those attributes after a payment has been successfully created with a Stripe payment method.

Vipps

Additional request's Attribute

Attribute

Type

Description

metadata.redirect_url

string

The fallback URL is the URL users will be redirected to after completing a payment through the Vipps App. It can be defined by the client or by the company Vipps setting: default vipps fallback

Additional Payment attributes

Attributes

Type

Description

metadata.vipps_url

string

The URL used to confirm the Vipps phone number and send a payment request to the Vipps APP.

metadata.vipps_auth_token

string

A token generated by BuiltOn while creating a Vipps Payment.

You will get those attributes after a payment has been successfully created with a Vipps payment method.

*Paths listed below with an asterisk are accessible to both User and Admin Roles.

Payment for Orders*

Pay for an Order or multiple Orders at once.

Parameters
HTTP - Stripe
HTTP - Vipps
Parameters

Arguments

Type

Description

orders

array

List with Orders to be paid.

payment_method

string

Selected Payment Method id to use.

HTTP - Stripe
Request --
POST /payments HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"orders": [<order_id>],
"payment_method": <stripe_payment_method_id>
}
Response --
HTTP/1.1 200 OK
Content-Type: application/json
{
"company": {
"$oid": "57ee9c71d76d431f8511142f"
},
"created": {
"$date": 1476118043580
},
"_id": {
"$oid": "<payment-id>"
},
"modified": {
"$date": 1476118043580
},
"deleted": false,
"user": {
"$oid": "57ee9c72d76d431f85111432"
},
"amount": 450.2,
"current_state": "created",
"active": true,
"human_id": "51Q4LN",
"currency": "NOK",
"subject": "<order-id>",
"payment_method": "<stripe_payment_method_id>",
"payment_date": {
"$date": 147998016470
},
"metadata": {
"payment_method": "<payment-id>",
"payment_intent_id": "stripe-payment-intent-id",
"intent_client_secret": "stripe-intent-client-secret"
}
}
HTTP - Vipps
Request --
POST /payments HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"orders": [<order_id>],
"payment_method": <vipps_payment_method_id>,
"metadata": {
"redirect_uri": "https://your-redirect-uri"
}
}
Response --
HTTP/1.1 200 OK
Content-Type: application/json
{
"company": {
"$oid": "57ee9c71d76d431f8511142f"
},
"created": {
"$date": 1476118043580
},
"_id": {
"$oid": "<payment-id>"
},
"modified": {
"$date": 1476118043580
},
"deleted": false,
"user": {
"$oid": "57ee9c72d76d431f85111432"
},
"amount": 450.2,
"current_state": "created",
"active": true,
"human_id": "51Q4LN",
"currency": "NOK",
"subject": "<order-id>",
"payment_method": "<vipps_payment_method_id>",
"payment_date": {
"$date": 147998016470
},
"metadata": {
"redirect_uri": "https://your-redirect-uri",
"vipps_auth_token": 'vipps-token',
"vipps_url": "https://apitest.vipps.no/dwo-api-application/v1/deeplink/vippsgateway?v=2&token=vipps-token"
}
}

Retrieve a Payment*

Parameters
Request
Response
Parameters

Argument

Type

Description

payment-id

string

ID of the queried payment.

Request
GET /payments/<payment-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-id>"
},
"modified": {
"$date": 1476118043580
},
"deleted": false,
"user": {
"$oid": "57ee9c72d76d431f85111432"
},
"amount": 450.2,
"metadata": {},
"current_state": "created",
"active": true,
"human_id": "51rQxLN",
"currency": "NOK",
"subject": "<invoice-id>",
"payment_method": "<payment-method-id>",
"payment_date": {
"$date": 147998016470
}
}

List all Payments*

Parameters
Request
Response
Parameters

Query Parameters

Type

Description

size

number

Number of resources per page. Default is 10.

page

number

Defines which page to retrieve. Default is 0.

from_date

number

Start date, timestamp format. Default is None.

to_date

number

End date, timestamp format. Default is None.

sort

string

Field used to sort results.

status

string

Status of the payment.

Request
GET /payments 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-id>"
},
"modified": {
"$date": 1476118043580
},
"deleted": false,
"user": {
"$oid": "57ee9c72d76d431f85111432"
},
"amount": 450.2,
"metadata": {},
"current_state": "created",
"active": true,
"human_id": "51Q4LN",
"currency": "NOK",
"subject": "57ee9c72d76d431f85111434",
"payment_method": "<payment-method-id>",
"payment_date": {
"$date": 147998016470
}
}
]

Update Payment*

Only the below fields are editable in a payment.

Parameters
Request
Response
Parameters

Arguments

Type

Description

active

boolean

Default is True.

payment_method

string

ID for payment method.

billing_address

string

The Billing Address for they payment method.

payment_date

number

Update payment date, timestamp format.

Request
PUT /payments/<payment_id> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"active": false
}
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"currency": "NOK",
"amount": 390,
"active": false,
"human_id": "MR998V",
"subject": {
"_cls": "Invoice",
"_ref": "5c641635fd1c45001219e849"
},
"_id": {
"$oid": "5c641640fd1c45001519e84a"
},
"accounting_reference": "400367",
"metadata": {},
"deleted": false,
"company": {
"$oid": "59ce1e0a9d3bde0006fa45a9"
},
"user": {
"$oid": "5c1cc0c3ae702b00123f99fb"
},
"modified": {
"$date": 1552912011146
},
"created": {
"$date": 1550063168924
},
"current_state": "succeeded"
}