Integrations & ERP Custom Fields / API Developer Documentation

Refer to our Swagger Developer API UI as a testbed to try out the APIs (there is a similar one for Production with a different URL).

This article explains how to get up and running using the Swagger UI to connect to your YayPay Development Instance and test a few API /Get or /Post calls.

Authorization

There are two available methods of authorization via API key and OAuth token.

  • In the Swagger UI page, initiate the API Authorization by clicking on the button “Authorize” to enter your API Key or client id and client secret for OAuth:Integrations & ERP Custom Fields / API Developer Documentation
  • Enter your credentials and click “Authorize” to start your tests

Integrations & ERP Custom Fields / API Developer Documentation

example for authorization with API key

Integrations & ERP Custom Fields / API Developer Documentation

example for OAuth authorization

Start transaction

Start the Request using /batch/start to begin a transaction to upload data to YayPay.

  • The start_period and end_period define the time range of when the new records and updates occurred in. For example:
    • If your invoice data was created on 3/31and you choose the period 4/1 to 4/15, the Invoice record will not be added to YayPay since it falls outside the time range
    • If there was another Invoice record (e.g. it is partially paid on 4/3), this record will be included in the API request
  • Use “OTHER” for the Name of the source system
See Also:  Infor vs NetSuite: Which Is The Better Option?

Integrations & ERP Custom Fields / API Developer Documentation

The successful Request will contain a transaction ID (in the Response body).

Take note of this transaction ID as you will need to use it for other further Requests. It is mandatory that you use this same ID for all Requests.

Integrations & ERP Custom Fields / API Developer Documentation

Note: As you did when starting the Request using /batch/start to begin the transaction, you will eventually end the Request using /batch/finish, explained later.

API Parameters shown in the Swagger UI

All API parameters are shown under the Model tab. Mandatory fields are shown by a red asterisk (*) next to the parameter name:

Integrations & ERP Custom Fields / API Developer Documentation

Try your First API Upload

Create your first data upload in your YayPay Development instance comprising a customer, contact, an invoice and payment to help you gain familiarity.

The next few examples outline the steps of using the API Requests to upload data into YayPay, and also to help you understand the logic about Paid/Unpaid invoices coupled with applied/unapplied Payments to the Invoices:

  1. Create a Customer – This is a basic first step to ensure there is a Customer master record in YayPay
  2. Create a Contact – This is to create a Customer-level Billing Contact that is important when users automate the Collection Process by sending Email Reminders to these contact(s) as recipients
  3. Create an Invoice – This will enable the Finance / AR team and the Customer to view the information about paid/unpaid invoices, which will also change the Customer’s balance
  4. Create a Payment – This is to show the payments received in your ERP, and details about the link between the payment and the invoice (i.e. how much of the payment was applied to the Invoice)
See Also:  Waste Industry Solutions

Do not forget to begin the transaction with /batch/start.

1. Create a Customer record

Use the POST /customers Request:

  • Include the appropriate information, including mandatory fields (look at the Model tab)

Request example:

Integrations & ERP Custom Fields / API Developer Documentation

Integrations & ERP Custom Fields / API Developer Documentation

2. Create a Customer Contact

Use the POST /contacts request:

  • Include the appropriate information, including mandatory fields (look at the Model tab)
  • Ensure you define the correct internal ID of the customer used previously (1)

Request example:

Integrations & ERP Custom Fields / API Developer Documentation

Integrations & ERP Custom Fields / API Developer Documentation

Same request but “primary” flag set to false:

Integrations & ERP Custom Fields / API Developer Documentation

Integrations & ERP Custom Fields / API Developer Documentation

3. Create an Invoice

Use the POST /invoices request:

  • Include the appropriate information, including mandatory fields (look at the Model tab)
  • Ensure you define the correct internal ID of the customer you used previously
  • Ensure you define the correct internal ID of the contact you used previously
  • Use the date format: YYYY-MM-DDThh:mm:ss+hh:mm (it is mandatory to add the timezone)
  • Add the Transaction ID that was generated when you started the transaction

Request example:

Integrations & ERP Custom Fields / API Developer Documentation

Integrations & ERP Custom Fields / API Developer Documentation

Integrations & ERP Custom Fields / API Developer Documentation

4. Create the payment

Use the POST /payments request:

  • Include the appropriate information, including mandatory fields (look at the Model tab)
  • Ensure you define the correct internal ID of the customer and the Invoice used previously
  • Ensure you define the correct internal ID of the invoice and Invoice used previously
  • Use the date format: YYYY-MM-DDThh:mm:ss+hh:mm (it is mandatory to add the timezone)
  • Add the transaction ID that was generated when you started the transaction

Request example:

Integrations & ERP Custom Fields / API Developer Documentation

Integrations & ERP Custom Fields / API Developer Documentation

Integrations & ERP Custom Fields / API Developer Documentation

5. Commit transaction and apply updates

When you finish updating data and want to post it in the Database, you will need to close the transaction.

See Also:  10 Best SolarWinds Papertrail Alternatives in 2023

Use the request /batch/finish to do this, after which you can search the new records and updates in YayPay.

Integrations & ERP Custom Fields / API Developer Documentation

REST API Clients

For testing purposes, you can utilize browser extensions, such as API Tester for Chrome, or Postman client that will allow you to interact with REST services. With the help of the easy-to-use request editor, one cycle (start transaction -> add customer -> finish transaction) will look like as follows:

1) start a transaction:

https://www.developer.yaypay.com/api/v1/batch/start?end_period=2020-11-10T23:59:59&source_system=OTHER&start_period=2020-11-10T23:59:59

Integrations & ERP Custom Fields / API Developer Documentation

Once the request is sent, you can inspect the API response at the bottom of the page

Integrations & ERP Custom Fields / API Developer Documentation

2) create customers:

https://www.developer.yaypay.com/api/v1/customers?transaction_id=483123

Integrations & ERP Custom Fields / API Developer Documentation

API response

Integrations & ERP Custom Fields / API Developer Documentation

3) finish transaction

https://www.developer.yaypay.com/api/v1/batch/finish?transaction_id=483123

Integrations & ERP Custom Fields / API Developer Documentation

The customer record in YayPay will look like this

Integrations & ERP Custom Fields / API Developer Documentation

Related Posts

What Distinguishes a SaaS Platform from Regular Software Applications?

I this blog, we will discuss What Distinguishes a SaaS Platform from Regular Software Applications? in detail.You might be interested in Subscriptio – WooCommerce Subscriptions 3.0.6 11…

What Is Enterprise SaaS? (With Examples)

SaaS is all around us.You might be interested in 14 Best White Label Tools for Agencies EdgeWave Email Filtering Appliance – MAG4000 Message Assurance Gateway Appliances (MAG)…

SaaS Implementation: What are the Essential Steps to Implementing it?

SaaS (Software as a Service) has been adopted by a staggering number of organizations in recent years. The reason for such a huge adoption rate is that…

A Beginners Guide to SaaS Content Writing

Content writing is becoming an increasingly important part of marketing strategies designed for SaaS companies. And the reason for this is simple.You might be interested in Linear…

How to negotiate a SaaS contract

Nearly every company in the world has undergone a digital transformation. This means that there’s not a company out there that’s not buying, managing and renewing software…

SaaS backup

What Is SaaS Backup? Software as a Service backup, or SaaS backup, is the process of duplicating and storing data generated from using SaaS products. This data…