Quickstart

Let's get started with the Payable APIs and create your first reconciliation report.

This report will reconcile payments from a Checkout.com transactions report against actual transactions from a bank account of your choosing.

Before we get started open up a terminal where you have permissions to run some cURL commands.

Now, to get an account, please chat with the Payable team here [email protected] if you have not already. Then navigate to your API key within your Payable Dashboard and make a note of it. Please keep your key a secret and do not share it with anyone.

Once you have a Payable account and an API key it's time to upload your first transactions report file. We support a number of different file schemas. One of them being a Checkout.com transactions report, you can find one of those in your Checkout.com dashboard. We'll use that to match transactions from your bank account.

Now run the following cURL command to get an upload link where you can upload your Checkout.com transactions report.

🚧

Make sure you are replacing <YOUR_API_KEY_HERE> with your actual API key that you received earlier on every call.

curl --request POST \
     --url 'https://api.payable.co/files' \
     --header 'X-Api-Version: 1.0' \
     --header 'X-Api-key: <YOUR_API_KEY_HERE>' \
     --header 'X-Idempotency-Key: b52fAz9rRUmQNeFbYIp33A' \
     --header 'X-Request-Id: ITSBMkBs3kaXaAn25ImSLw' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "file_name": "test-file.csv",
     "purpose": "reconciliation",
     "schema": "checkout_transactions_report"
}
'

Once you get a upload link, use it upload the checkout.com transactions report.

curl --location --request PUT '<upload url>' \
         --header 'Content-Type: text/csv' \
         --data-binary '@<location of the file>'

Congratulations you just uploaded your first file to use for reconciliation!

Now let's connect an account to reconcile your checkout.com transactions report against your bank account transactions.

curl --request POST \
     --url 'https://api.payable.co/connections' \
     --header 'X-Api-Version: 1.0' \
     --header 'X-Api-key: <YOUR_KEY_HERE>' \
     --header 'X-Idempotency-Key: b52fAz9rRUmQNeFbYIp33A' \
     --header 'X-Request-Id: ITSBMkBs3kaXaAn25ImSLw' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "label": "My-OpenBanking-Account",
     "institution_id": "OpenBanking"
}
'

You will receive a link from the call to connect your bank account. Follow this link to give consent for Payable to link an account so we can see the transactions.

📘

Sources

Every file you upload with a purpose of reconciliation, and every bank account you connect becomes a source that its useable for various reports.

Now let's check that the file you uploaded and account you connected have appeared as sources for the reconciliation report. Make a note of the ids returned here for your uploaded file and bank account. We will need these next to use for a reconciliation report.

curl --request GET \
     --url 'https://api.payable.co/sources?skip=0&limit=25' \
     --header 'X-Api-key: <YOUR_KEY_HERE>' \
     --header 'X-Request-Id: ITSBMkBs3kaXaAn25ImSLw' \
     --header 'accept: application/json'

Now it's time to generate a reconciliation report.

🚧

Replace <YOUR_FILE_ID_HERE> with file id you made a note of earlier from the call to the sources endpoint. Finally replace <YOUR_ACCOUNT_ID_HERE> with your bank account id that you obtained earlier in that same sources call.

The call will return a report Id. Make a note of it so we can check the status of the report and ultimately get the results.

curl --request POST \
     --url 'https://api.payable.co/reports' \
     --header 'X-Api-key: <YOUR_KEY_HERE>' \
     --header 'X-Idempotency-Key: b52fAz9rRUmQNeFbYIp33A' \
     --header 'X-Request-Id: ITSBMkBs3kaXaAn25ImSLw' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "template_id": "test_template_id",
     "sources": [
          "fil_<YOUR_FILE_ID_HERE>",
          "acc_<YOUR_ACCOUNT_ID_HERE>"
     ]
}
'

Now that we have a reconciliation report being created we can check its status with this call.

🚧

Replace the REPORT_ID with the report id you made a note of earlier from call to generate a report.

curl --request GET \
     --url 'https://api.payable.co/reports/<REPORT_ID>' \
     --header 'X-Api-key: <YOUR_KEY_HERE>' \
     --header 'X-Request-Id: ITSBMkBs3kaXaAn25ImSLw' \
     --header 'accept: application/json'

Once the report is done we can get the results by making a call to the results endpoint. It's a similar call to the one made to check the status of the report, but with a /results appended to the path.

curl --request GET \
     --url 'https://api.payable.co/reports/<REPORT_ID>/results' \
     --header 'X-Api-key: <YOUR_KEY_HERE>' \
     --header 'X-Request-Id: ITSBMkBs3kaXaAn25ImSLw' \
     --header 'accept: application/json'

Congratulations you have just run your first reconciliation report with Payable!

👍

Let's recap what you have done.

Created a Payable account
Uploaded a checkout.com transactions file report
You have linked a bank account through Open Banking
You got a list of sources that could be used for reports
Finally you generated a report, checked it's status and got the results

Phew! That was a lot, you should be proud of what you have accomplished.

If you need help with anything, send us a message and we will be happy to help!