API Reference
API Reference

Authentication

OAuth2 Client Credential Flow

Assembly Payments APIs implement OAuth2 credential flow for authentication. Clients are required to acquire 60-minute Bearer tokens from an issuing server prior to interacting with the Assembly Payments APIs.

The token issuing server urls including the API path are as follows:

Assembly Payments will issue you with a Client Code, Client Secret and Scope that you will need to pass to the API above. These fields can be found in the Assembly Payments Dashboard under the Platform Profile.

As a result of calling the Token API a Bearer token is returned. The returned Bearer token should be included in the header of API calls as follows

Authorization: Bearer ZGVtbzpwQDU1dzByZA==

The following code examples show the client code used to call the list users API with the dummy authorization header values above

curl -X GET \
  https://test.api.promisepay.com/users \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer ZGVtbzpwQDU1dzByZA=='

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://test.api.promisepay.com/users?limit=10&offset=0&search=search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["Authorization"] = 'Basic ZGVtbzpwQDU1dzByZA=='

response = http.request(request)
puts response.read_body

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://test.api.promisepay.com/users?limit=10&offset=0&search=search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "Authorization: Basic ZGVtbzpwQDU1dzByZA=="
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

var data = null;

var xhr = new XMLHttpRequest();

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://test.api.promisepay.com/users?limit=10&offset=0&search=search");
xhr.setRequestHeader("accept", "application/json");
xhr.setRequestHeader("Authorization", "Basic ZGVtbzpwQDU1dzByZA==");

xhr.send(data);

var client = new RestClient("https://test.api.promisepay.com/users?limit=10&offset=0&search=search");
var request = new RestRequest(Method.GET);
request.AddHeader("accept", "application/json");
request.AddHeader("Authorization", "Basic ZGVtbzpwQDU1dzByZA==");
IRestResponse response = client.Execute(request);

package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://test.api.promisepay.com/users?limit=10&offset=0&search=search"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("accept", "application/json")
	req.Header.Add("Authorization", "Basic ZGVtbzpwQDU1dzByZA==")
	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

FAQs:
Q: How long do the tokens last?
A: The tokens last for 60 minutes. In the API response of the Token API the returned field expires_in indicates the period the token will be valid for in seconds. We recommend you maintain that in order to know when to request a new token

Q: Do you support refreshing tokens?
A: We do not support refreshing of tokens. You will need to track the token you have and request a new one close to/after it has expired.

Q: Do I need to maintain and track the tokens or can I simply just get a token for every API call?
A: Our recommended approach is that you maintain and track the tokens expiry and only get a new one closer to the expiry time. While our token issuing server can generate multiple tokens, it does have limits on how many time you can call the Token API. If you do request it too many times you will encounter an error from the API due to throttling.

Note: The auto generated code examples for this section of the documentation of all the APIs does not include the authentication header values so please remember to add them for all API calls your client plans to execute