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
amount_paid
number
Amount as a Float with decimal points. Example: 10.23 USD
amount_reserved
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, cancelled, reserved, refunded, partial_refund, pending_refund, refund_failed and on_retry.
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"
}

Subscriptions

Setup a Payment Provider

Last updated 1 month ago

Attributes	Type	Description
`user`	`object`	The `user` associated with the Payment.
`amount`	`number`	Amount as a Float with decimal points. Example: 10.23 USD
`amount_paid`	`number`	Amount as a Float with decimal points. Example: 10.23 USD
`amount_reserved`	`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`, `cancelled`, `reserved`, `refunded`, `partial_refund`, `pending_refund`, `refund_failed` and `on_retry`.
`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.

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`

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