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:
  
  
• Enter your credentials and click "Authorize" to start your tests

example for authorization with API key

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
  
  

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.

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:

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)

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:

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:

Same request but "primary" flag set to false:

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:

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:

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. 

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

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

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

2) create customers:

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

API response

3) finish transaction

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

The customer record in YayPay will look like this