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 or Subscription ID.
current_state
string
Current state of payment. 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 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.
Paths listed below and denoted with a star are accessible to both User and Admin Roles.
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"
}
*Paths listed above and denoted with a star are accessible to both Users and Admins. 

Subscriptions

Setup a Payment Provider

Last updated -4

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 or Subscription ID.
`current_state`	`string`	Current state of payment. 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 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.

Arguments	Type	Description
`orders`	`array`	List with `Orders` to be paid.
`payment_method`	`string`	Selected `Payment Method` id to use.

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.

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.

Argument	Type	Description
`payment-id`	`string`	ID of the queried payment.