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

Attribute

Type

Description

user

object

The user associated with 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 character long.

subject

string

Order reference.

current_state

string

Current state of operation. Can be one of: 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 .

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.

Payment for Orders

Pay for an Order or multiple Orders at once.

Parameters
Request
Response

Arguments

Type

Description

orders

array

List with Orders to be paid.

payment_method

string

Selected Payment Method id to use.

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": "<payment-method-id>"
}
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": "<order-id>",
"payment_method": "<payment-method-id>",
"payment_date": {
"$date": 147998016470
}
}

Retrieve a Payment

Parameters
Request
Response

Argument

Type

Description

payment-id

string

ID of the queried payment.

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

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.

GET /payments 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-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

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.

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