Payments
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.
Base
Stripe
Vipps
Attributes | Type | Description |
user | object | |
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 | |
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 | |
billing_address | object | |
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. |
Attributes | Type | Description |
metadata.payment_intent.id | string | |
metadata.intent_client_secret | string |
You will get those attributes after a payment has been successfully created with a Stripe payment method.
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 |
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.
Pay for an Order or multiple Orders at once.
Parameters
HTTP - Stripe
HTTP - Vipps
Arguments | Type | Description |
orders | array | |
payment_method | string |
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"
}
}
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"
}
}
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
}
}
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
}
}
]
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"
}
Last modified 2yr ago