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

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

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

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

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

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