Paytron Links

When working with APIs, you can often find yourself going back and forth to retrieve all of the data required to perform a single task in your application, simply because each response only provides you with pointers to the next piece of information. (A.k.a. the n+1 problem).

To help reduce the number of calls you need to make, Paytron provides links to any related resources, which can optionally enriched with the full resource data. These links are available to you as long as the endpoint you're calling returns some kind of response, i.e. most get/create/update calls, with the exception of delete or similar calls returning a 204 - No Content response.

This page gives a quick introduction on how to use those links to get all the data you need in a single call.

Links

To make sure you don't have to come back to us multiple times to get your data, each API supports includes a set of links that can be enriched through the include query string parameter.

Any endpoint that returns a body response will also include a links section, describing related entities in Paytron and how to reach them. For example, when creating a new payment, the response will include a link to the quote associated with that payment.

But who wants to be making multiple calls to get this information? That's where the include query string parameter comes into play.

🚧

Links and response times

Paytron will try to minimise the effect on response times when fetching linked resources, however doing the extra work to provide the information will always have some cost.

Please keep in mind that using links may cause some responses to be slower, particularly list operations where a large number of items are being returned.

How to use include

The include query string parameter can be used to make the Paytron API returned the full information for any supported resource.

The value of this parameter is a simple comma separated list, where the values are the plural of whatever resource you want need more information on, for example bills, or quotes. The links section will then be expanded to include the full version of that resource.

For example, say you are creating a new payment and want to know more about the quote you've agreed to with Paytron, and the conversion that's been booked for you. When creating the payment you would include the query string: ?includes=quotes,conversions.

If your create request is successful, the links section of your payment response may look something like this:

{
	"links": {
   	"beneficiary": {
     	"id": "1234-5678",
       "url": "https://beneficiaries.api.paytron.com/1234-5678"
    },
     "quote": {
      	 "id": "abcd-efgh",
         "beneficiaryId": "1234-5678",
         "amount": 100.00,
         "fundingAmount": 123.40,
         "fees" : {
          	"transactionFee": 0.5,
            "fxMarginPercent": 1.234,      
         },
         "fixedSide": "BUY",
         "currency": "AUD",
         "fundingCurrency": "NZD",
         "createdAt": "2023-01-23T11:21:00.124Z",
         "createdBy": "User-1234",
         "validUntil": "2023-01-23T13:21:00.124Z"
     },
     "conversion": {
      	"id": "conversion-1234",
        "paymentId": "payment-1234",
        "fixedSide": "BUY",
        "marginRate": 0.000,
       	"originalMarketQuote": 1.234,
        "rate": 1.234,
        "status": "SCHEDULED",
        "conversionDate": "2023-01-24",
        "fundingCurrency": "NZD",
        "fundingAmount": 100,
        "marginAmount": 0.00,
        "currency": "AUD",
        "amount": 123.40,
        "createdAt": "2023-01-23T11:21:00.124Z",
        "createdBy": "User-1234"
     }
  }
}