PayNau

Introduction

API Reference

Errors

Authorization

OAuth2.0 Token Generation

Standard Codes and Values

Pay In - Direct API Integration

Pay In Payment Options

Pay In Payment Processing

Query Pay In Transactions

Refunds

Pay Out - Direct API Integration

Pay Out Payment Processing

Query Pay Out Transactions

Pay In - PayURL Integration

PayURL Service

PayURL with Custom Payment Method List

PayURL with Customer Data in Request

Redirect the user to the generated PayURL

Transactions Status Notification

Query Balance

Appendix

FastAPI

PayPaga

Production

Sandbox

<p class="slate-p slate-indent-1" style="24px">PayPaga Integration alternatives are as follows:</p><p class="slate-p slate-indent-1" style="24px"><strong class="slate-bold">Payment Widget Integration</strong></p><p class="slate-p slate-indent-1" style="24px">Coming soon.</p><p class="slate-p slate-indent-1" style="24px"><strong class="slate-bold">Direct API Integration</strong></p><p class="slate-p slate-indent-1" style="24px">The Direct API integrations allows full control over the flow and interactions with the consumer.</p><p class="slate-p slate-indent-1" style="24px">API requests are secured with OAuth2.0 authorisation.</p><p class="slate-p slate-indent-1" style="24px"><strong class="slate-bold">PayURL Integration</strong></p><p class="slate-p slate-indent-1" style="24px">This provides a web funnel solution for pay-ins to be integrated as part of the merchants&apos; checkout experience.  </p><p class="slate-p " ></p><p class="slate-p " ></p>

PayPaga Integration alternatives are as follows:

The Direct API integrations allows full control over the flow and interactions with the consumer.

API requests are secured with OAuth2.0 authorisation.

This provides a web funnel solution for pay-ins to be integrated as part of the merchants' checkout experience.  

<p class="slate-p slate-indent-1" style="24px">The PayPaga API is organized around <a href="https://en.wikipedia.org/wiki/Representational_State_Transfer" target="_self">REST</a>. The API has predictable resource-oriented URLs, accepts <a href="https://www.json.org/" target="_self">JSON-encoded</a> request bodies, returns JSON-encoded responses and uses standard HTTP response codes, authentication, and verbs.</p><p class="slate-p slate-indent-1" style="24px">The PayPaga API has a segregated sandbox test environment which allows integration testing without affecting Production data or interacting with live payment networks. </p><p class="slate-p slate-indent-1" style="24px">
PayPaga considers the following changes to be backwards-compatible:</p><div class="table-container"><table class="slate-table" style="width:60%;
  min-width:60%;"><colgroup ><col style="width:0%"><col style="width:0%"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Adding new API resources</div></li><li class="slate-li " ><div style="position:relative">Adding new optional request parameters to existing API methods</div></li><li class="slate-li " ><div style="position:relative">Adding new properties to existing API responses</div></li><li class="slate-li " ><div style="position:relative">Changing the order of properties in existing API responses</div></li></ul></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ></p></td></div></tr></tbody></table></div><p class="slate-p slate-indent-1" style="24px">When making requests to the PayPaga API we recommend using a timeout of 30 seconds as some requests can take longer than expected since they rely on communicating with a payment processor.

</p><p class="slate-p " ></p><p class="slate-p " ></p>

. The API has predictable resource-oriented URLs, accepts 

 request bodies, returns JSON-encoded responses and uses standard HTTP response codes, authentication, and verbs.

The PayPaga API has a segregated sandbox test environment which allows integration testing without affecting Production data or interacting with live payment networks. 


PayPaga considers the following changes to be backwards-compatible:

When making requests to the PayPaga API we recommend using a timeout of 30 seconds as some requests can take longer than expected since they rely on communicating with a payment processor.



<p class="slate-p slate-indent-1" style="24px">The PayPaga API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: </p><p class="slate-p slate-indent-2" style="48px"></p><p class="slate-p slate-indent-2" style="48px">Codes in the 2xx range indicate success. </p><p class="slate-p slate-indent-2" style="48px">Codes in the 4xx range indicate an error with the request content such as a required parameter was omitted or had an invalid format.</p><p class="slate-p slate-indent-2" style="48px">Codes in the 5xx range Indicate the server could not process the request due to an unexpected condition. We work hard to make them as rare as possible
</p><p class="slate-p slate-indent-2" style="48px"></p><p class="slate-p slate-indent-2" style="48px">Some 4xx errors that could be handled programmatically (e.g., a card is declined) include additional information such as an error code to enable more nuanced error handling..</p><p class="slate-p " ></p><p class="slate-p " ></p>

The PayPaga API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: 

Codes in the 2xx range indicate success. 

Codes in the 4xx range indicate an error with the request content such as a required parameter was omitted or had an invalid format.

Codes in the 5xx range Indicate the server could not process the request due to an unexpected condition. We work hard to make them as rare as possible


Some 4xx errors that could be handled programmatically (e.g., a card is declined) include additional information such as an error code to enable more nuanced error handling..

200 - OK

Problem consuming the request due to not adhering to the API specification

400 - Bad request

Authorisation required due to invalid, expired or missing authorisation token

401 - Unauthorized

402 - Request Failed

The authorisation token does not have permissions to perform the request

403 - Forbidden

404 - Not Found

Server could not process the request due to an unexpected condition.  We work hard to make them as rare as possible

500, 502, 503, 504

<h3 class="slate-h3 " >Standards that define the possible values for common data types used in all APIs.

Country</h3><p class="slate-p slate-indent-1" style="24px">ISO 3166-1 Alpha 2 is the standard used for country codes, see <a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2" target="_self">ISO 3166-1 Alpha-2 codes for further reference</a></p><h3 class="slate-h3 " >Currency</h3><p class="slate-p slate-indent-1" style="24px">ISO 4217 alphabetic code is the standard used for currency codes, see <a href="https://en.wikipedia.org/wiki/ISO_4217" target="_self">ISO 4217 for further reference</a></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " > </p><p class="slate-p " ></p><p class="slate-p " ></p>

Standards that define the possible values for common data types used in all APIs.

ISO 3166-1 Alpha 2 is the standard used for country codes, see 

ISO 4217 alphabetic code is the standard used for currency codes, see 

<p class="slate-p " >An advanced workflow designed for customised integrations where the merchant will manage the complete consumer experience leveraging a backend integration for the transaction processing. The workflow steps are listed below and illustrated in the sequence diagram.</p><ol class="slate-ol " ><li class="slate-li " ><div style="position:relative">Prior to any transaction processing the Merchant must configure a Notification Method in the Developer&apos;s section of the Merchant Portal for the corresponding environment to enable transaction lifecycles notifications.</div></li><li class="slate-li " ><div style="position:relative">Call <a href="https://docs.paypaga.com/authorization/oauth2-0-token-generation" target="_self">OAuth2.0 Token Generation</a> and retrieve OAuth2.0 token </div></li><li class="slate-li " ><div style="position:relative">Using the OAuth2.0 token, the Merchant will interact with PayPaga API in two steps per transaction as follows: </div><ol class="slate-ol " ><li class="slate-li " ><div style="position:relative">Call the <a href="https://docs.paypaga.com/pay-in-direct-api-integration/pay-in-payment-options" target="_self">Pay In Payment Options</a> request to retrieve the current selection of orchestrated Payment Methods with corresponding data requirements</div></li><li class="slate-li " ><div style="position:relative">Call the <a href="https://docs.paypaga.com/pay-in-direct-api-integration/pay-in-payment-processing" target="_self">Pay In Payment Processing</a> request with selected Payment Method, supplying any Payment Method specific data </div></li></ol></li><li class="slate-li " ><div style="position:relative">Action payment lifecycle notifications sent to the registered notification method. </div></li></ol><p class="slate-p " ></p><div style="text-align:center"><img src="https://theneo-prod-public.s3.us-east-1.amazonaws.com/images-1703793772061.jpg" style="
              width:1497px;
	            height:667px;
	            aspect-ratio:1497 / 667"
         /></div><p class="slate-p " ></p><p class="slate-p " ></p>

An advanced workflow designed for customised integrations where the merchant will manage the complete consumer experience leveraging a backend integration for the transaction processing. The workflow steps are listed below and illustrated in the sequence diagram.

<p class="slate-p " >Execute Pay Out transactions.</p><p class="slate-p " ></p><div style="text-align:left"><img src="https://theneo-prod-public.s3.us-east-1.amazonaws.com/9f7676e4-5637-437f-baa3-8a072af64155.png" style="
              width:1497px;
	            height:603px;
	            aspect-ratio:1497 / 603"
         /></div><p class="slate-p " ></p><p class="slate-p " ></p>

<p class="slate-p " >The PayPaga PayURL is a customized checkout webpage to allow the selection of a payment method, entering any required information and submitting the payment. </p><p class="slate-p " >The workflow steps are listed below: </p><ol class="slate-ol " ><li class="slate-li " ><div style="position:relative">Call <a href="undefined" target="_blank"><u class="slate-underline">OAuth2.0 Token Generation</u></a> and retrieve OAuth2.0 token.</div></li><li class="slate-li " ><div style="position:relative">Using the OAuth2.0 token, call the <a href="undefined" target="_blank"><u class="slate-underline">Get PayURL</u></a> endpoint to get a new PayPaga PayURL based on the parameters provided in the request. </div></li><li class="slate-li " ><div style="position:relative">Redirect the user to the generated PayPaga PayURL. </div></li><li class="slate-li " ><div style="position:relative">The PayPaga PayURL will present to the user a list of payment methods previously approved by the merchant for the specified country. </div></li><li class="slate-li " ><div style="position:relative">Then, the user selects their preferred payment method, enters any required information and submits the payment. </div></li><li class="slate-li " ><div style="position:relative">Upon successful submission, the payment result is displayed, including instructions for asynchronous payments. A new transaction with status of PENDING will be created in the system. </div></li></ol><p class="slate-p " >

</p><p class="slate-p " ></p>

The PayPaga PayURL is a customized checkout webpage to allow the selection of a payment method, entering any required information and submitting the payment. 

<p class="slate-p " ></p><p class="slate-p " >The PayPaga platform provides Transaction Status Notifications that can be sent to a merchant defined API URL and/or to an email address list.  Configuration of transaction status notifications is performed via the Developer&apos;s section of the Merchant Portal for each environment. The configuration uses a JSON format, the following is an example:</p><div class="code-block-wrapper"  style="width:100%;min-width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">{</div><div class="slate-code_line">  &quot;notificationActivation&quot;: {</div><div class="slate-code_line">    &quot;email&quot;: true,</div><div class="slate-code_line">    &quot;api&quot;: false</div><div class="slate-code_line">  },</div><div class="slate-code_line">  &quot;apiEndpoint&quot;: &quot;https://your-api-endpoint.com/your-webhook&quot;,</div><div class="slate-code_line">  &quot;failedWebhookEmailList&quot;: [</div><div class="slate-code_line">    &quot;user1@example.com&quot;,</div><div class="slate-code_line">    &quot;user2@example.com&quot;</div><div class="slate-code_line">  ],</div><div class="slate-code_line">  &quot;notificationEmailList&quot;: [</div><div class="slate-code_line">    &quot;user3@example.com&quot;,</div><div class="slate-code_line">    &quot;user4@example.com&quot;</div><div class="slate-code_line">  ]</div><div class="slate-code_line">}</div></code></pre></div><p class="slate-p " ><strong class="slate-bold">WARNING</strong>: The use of a port number in the apiEndpoint value is not allowed.</p><p class="slate-p " >The payload of the API call and email is as follows: </p><div class="code-block-wrapper"  style="width:100%;min-width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">{</div><div class="slate-code_line">  &quot;transaction_id&quot;: &quot;XXXXX-XXXX-XXXX-XXXXX&quot;,</div><div class="slate-code_line">  &quot;status&quot;: &quot;Cmpleted&quot;,</div><div class="slate-code_line">  &quot;merchant_id&quot;: &quot;XXXXX-XXXX-XXXX-XXXXX&quot;,</div><div class="slate-code_line">  &quot;transaction_type&quot;: &quot;payin or payout&quot;,  </div><div class="slate-code_line">  &quot;merchant_transaction_reference&quot;: &quot;XXXXXXXX-XXXX-XXX&quot;</div><div class="slate-code_line">}</div></code></pre></div><p class="slate-p " ></p><div class="slate-div"></div><p class="slate-p " ><strong class="slate-bold">RESPONSE:</strong></p><p class="slate-p " >Status code: <strong class="slate-bold">200</strong></p><p class="slate-p " >Body: Empty</p><p class="slate-p " >Any other status code will be considered failed webhook request.</p><p class="slate-p " ></p><p class="slate-p " ><strong class="slate-bold">Request attempts:</strong></p><p class="slate-p " >Paypaga will attempt the notification request 3 times. If all attempts fail an email will be sent to the configured <strong class="slate-bold">failedWebhookEmailList </strong>email list<strong class="slate-bold">.</strong></p><p class="slate-p " >The first retry will occur after 30 seconds with backoff rate multiplier duplicating timeout for every attempt , for example:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">First attempt FAILED</div></li><li class="slate-li " ><div style="position:relative">30 seconds later second attempt FAILED</div></li><li class="slate-li " ><div style="position:relative">60 seconds later third attempt FAILED, send email with Payload to <strong class="slate-bold">failedWebhookEmailList</strong></div></li></ul><p class="slate-p " >In order to retrieve more details about the notified transaction use the applicable ‘Transaction Query’ API relevant to the transaction type.
</p><p class="slate-p " ></p><p class="slate-p " ></p>

The PayPaga platform provides Transaction Status Notifications that can be sent to a merchant defined API URL and/or to an email address list.  Configuration of transaction status notifications is performed via the Developer's section of the Merchant Portal for each environment. The configuration uses a JSON format, the following is an example:

: The use of a port number in the apiEndpoint value is not allowed.

The payload of the API call and email is as follows: 

Any other status code will be considered failed webhook request.

Paypaga will attempt the notification request 3 times. If all attempts fail an email will be sent to the configured 

The first retry will occur after 30 seconds with backoff rate multiplier duplicating timeout for every attempt , for example:

In order to retrieve more details about the notified transaction use the applicable ‘Transaction Query’ API relevant to the transaction type.


Unique PayPaga assigned transaction identifier

transaction_id

status

Merchant identifier provided in the Developer's section of the merchant portal

merchant_id

transaction_type

Merchant supplied unique transaction identifier for correlation

merchant_transaction_reference

<p class="slate-p" placeholder="Type / for widgets">Real-time access to the financial balances of a merchant&apos;s account. This can be used for reporting and as a precursor to <a href="https://docs.paypaga.com/pay-out-direct-api-integration/pay-out-payment-processing" target="_self">Pay Out Payment Processing</a> to determine if there is sufficient balance.</p><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets">Error codes for Query Balance</p><table class="slate-table"><colgroup><col style="width:24.06417112299465%"/><col/></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets"><strong class="slate-bold">Error code</strong></p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets"><strong class="slate-bold">Description</strong></p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">107</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets"><span style="color:#000000;font-size:14px" class="slate-color">The merchant balance does not exist</span></p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">500</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets"><span style="background-color:rgb(255, 255, 255);color:#000000;font-size:14px" class="slate-color"><span style="background-color:rgb(255, 255, 255);color:#000000;font-size:14px" class="slate-backgroundColor">Unexpected error</span></span></p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr></tbody></table><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p>

Real-time access to the financial balances of a merchant's account. This can be used for reporting and as a precursor to 

 to determine if there is sufficient balance.

OAuth2.0 Bearer token returned from OAuth2.0 Token Generation API call

ISO 3166-1 Alpha 2 Country code where the transactions were processed.  If not provided the balances of all the countries available to the merchant will be returned.

country_code

Payment method which processed the transactions.  If not provided the balances of all the payment methods available to the merchant will be returned.

payment_method_code

country_collection

Transaction processing timestamp (UTC timezone)

datetime

Numeric error code. See code catalogue above.

error_code

message

version

<h3 class="slate-h3 " >Transaction Status Definitions and Lifecycle</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">&quot;Initiated&quot;</strong>: Set when a transaction intent is initiated either when the Payment widget is loaded or the Payin Payment Options API is called..</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">&quot;Authorizing&quot;</strong>: Set when a transaction intent is submitted to a Payment Provider for processing when a Payment Processing API endpoint is called.  The transaction remains in this state until the Payment Provider responds..</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">&quot;Pending&quot;</strong>: Set when a Payment Provider responds to the transaction processing request indicating successful receipt of the transaction.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">&quot;Reject&quot; (Final State)</strong>: Set when a Payment Provider responds to the transaction processing request indicating unsuccessful receipt of the transaction.. Final state indicating a failed transaction.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">&quot;Declined&quot; (Final State)</strong>: Set when a Payment Provider responds to the transaction processing request indicating processing was unsuccessful. Final state indicating a failed transaction.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">&quot;Canceled&quot; (Final State): </strong> Set when payment processing has been cancelled. Final state indicating a failed transaction.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">&quot;Refund&quot; (Not yet implemented)</strong>:  This status is reserved for future use for where a transaction is reversed.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">&quot;Approved&quot; (Final State)</strong>: Set when a Payment Provider confirms the successful completion of the payment lifecycle. Final state indicating a successful transaction.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">&quot;Error&quot; (Final State)</strong>: Set when an unexpected errors occurs during processing. Final state indicating a failed transaction.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">&quot;Expired&quot; (Final State): </strong>Set when a Pending transaction reach the time limit to be completed when an end user interaction is required. Final State indicating an incomplete transaction.</div></li></ul><p class="slate-p " ></p><p class="slate-p " ></p>

Transaction Status Definitions and Lifecycle

Sections