Server-to-Server

Server-to-Server Integration Guide

Last updated:April 30, 2024

Embark on a journey with our all-encompassing Server-to-Server guide, your ultimate companion for accepting and managing payments. This guide walks you through the entire payment journey, from start to finish. As a merchant, you’ll be in full control, collecting all card and payment details directly. This behind-the-scenes process ensures a smooth and seamless experience for your shoppers. Navigate the complexities of the payment landscape with ease and efficiency, all thanks to our Server-to-Server guide. Start your journey today!

PCI-DSS Compliance: To collect card data, you must be PCI-DSS compliant. To minimize your compliance requirements, please use PayUnity.Flex.
HTTP POST Requests: Remember, for an HTTP POST request, all parameters must be incorporated in the message body, not in the URL.
API Reference: Consult the API Reference for a detailed list of parameters that can be included in the payment request.

Use cases

Synchronous payment

The merchant collects card data from the shopper and initiates the synchronous payment flow.


How it works

Select your transaction flow. Be aware, some payment brands may not support your chosen flow. Check for compatibility.

Pre-authorize payment

Send the pre-authorization request with the collected card data.

Capture the payment

Send the capture request.

OPTIONAL

Manage the payment

Send the back-office payment request.

Transactions:
PA
PA
CP
CP
RF
RF
CB
CB
CR
CR
RB
RB

1. Pre-authorize payment

Initiate a server-to-server POST request with the required payment data. The payment details are verified with the issuer, and the funds are reserved. The response to a successful request is an id that should be stored and used in subsequent back-office operations.


2. Capture the payment

Initiate a server-to-server POST request over the pre-authorized payment. The reserved funds are transferred from the shopper's account to the merchant's account.

Sample request:

3. Manage the payment

Initiate a back-office server-to-server POST request over the captured payment to:

  • refund either the full captured amount or a part of the captured amount (see refund)
  • rebill the processed order for additional products (see rebill)
  • reflect the chargeback processed by the bank (see chargeback)
  • reflect the chargeback reversal processed by the bank (see chargeback)

Operation:

Sample request:

Perform debit payment

Send the debit request with the collected card data.

OPTIONAL

Manage the payment

Send the back-office payment request.

Transactions:
DB
DB
RF
RF
CB
CB
CR
CR
RB
RB

1. Perform debit payment

Initiate a server-to-server POST request with the required payment data. The payment details are verified with the issuer, and the funds are captured. The response to a successful request is an id that should be stored and used in subsequent back-office operations.


2. Manage the payment

Initiate a back-office server-to-server POST request over the debit payment to:

  • refund either the full captured amount or a part of the captured amount (see refund)
  • rebill the processed order for additional products (see rebill)
  • reflect the chargeback processed by the bank (see chargeback)
  • reflect the chargeback reversal processed by the bank (see chargeback)

Operation:

Sample request:

Asynchronous payment

The merchant collects card data from the shopper and initiates the asynchronous payment flow.


How it works

Select your transaction flow. Be aware, some payment brands may not support your chosen flow. Check for compatibility.

Pre-authorize payment

Send the pre-authorization request with the collected card data.

Redirect shopper

Redirect the shopper to validate and complete the payment.

Get the payment status

Find out if the payment was successful.

Capture the payment

Send the capture request.

Transactions:
PA
PA
CP
CP
OPTIONAL

Manage the payment

Send the back-office payment request.

Transactions:
RF
RF
CB
CB
CR
CR
RB
RB

1. Pre-authorize payment

Initiate a server-to-server POST request with the required payment data and the shopperResultUrl that must be url-encoded. The payment details are verified with the issuer, and the funds are reserved. The response to a successful request is an id that should be stored and used in subsequent back-office operations.


2. Redirect shopper

Initiate a server-to-server request to guide the account holder through the validation and completion of the payment. To facilitate this redirection, you need to interpret the redirect object from the response of the pre-authorized payment. This redirect object, along with its parameters, will be used in conjunction with an HTML form to perform the shopper’s redirect.

  • url: The HTTPS URL for redirection, used as the form’s action attribute.
  • method: Defaults to HTTPS POST, determines form submission method.
  • parameters: Appended to URL for HTTPS GET, or included in the body for HTTPS POST. In the case of an HTTPS POST, each parameter will be a hidden input field in the HTML form.

3. Get the payment status

Once the payment request is processed, the customer is redirected to your shopperResultUrl along with a GET parameter resourcePath.

resourcePath=/v1/payments/{id}

Sample request:

You’re allowed two payment status requests per minute per transaction. However, the query endpoint provides payment status without such restrictions.

4. Capture the payment

Initiate a server-to-server POST request over the pre-authorized payment. The reserved funds are transferred from the shopper's account to the merchant's account.

Sample request:

5. Manage the payment

Initiate a back-office server-to-server POST request over the captured payment to:

  • refund either the full captured amount or a part of the captured amount (see refund)
  • rebill the processed order for additional products (see rebill)
  • reflect the chargeback processed by the bank (see chargeback)
  • reflect the chargeback reversal processed by the bank (see chargeback)

Operation:

Sample request:

Perform debit payment

Send the debit request with the collected card data.

Redirect shopper

Redirect the shopper to validate and complete the payment.

Get the payment status

Find out if the payment was successful.

OPTIONAL

Manage the payment

Send the back-office payment request.

Transactions:
DB
DB
RF
RF
CB
CB
CR
CR
RB
RB

1. Perform debit payment

Initiate a server-to-server POST request with the required payment data and the shopperResultUrl that must be url-encoded. The payment details are verified with the issuer, and the funds are captured. The response to a successful request is an id that should be stored and used in subsequent back-office operations.


2. Redirect shopper

Initiate a server-to-server request to guide the account holder through the validation and completion of the payment. To facilitate this redirection, you need to interpret the redirect object from the response of the pre-authorized payment. This redirect object, along with its parameters, will be used in conjunction with an HTML form to perform the shopper’s redirect.

  • url: The HTTPS URL for redirection, used as the form’s action attribute.
  • method: Defaults to HTTPS POST, determines form submission method.
  • parameters: Appended to URL for HTTPS GET, or included in the body for HTTPS POST. In the case of an HTTPS POST, each parameter will be a hidden input field in the HTML form.

3. Get the payment status

Once the payment request is processed, the customer is redirected to your shopperResultUrl along with a GET parameter resourcePath.

resourcePath=/v1/payments/{id}

Sample request:

You’re allowed two payment status requests per minute per transaction. However, the query endpoint provides payment status without such restrictions.

4. Manage the payment

Initiate a back-office server-to-server POST request over the captured payment to:

  • refund either the full captured amount or a part of the captured amount (see refund)
  • rebill the processed order for additional products (see rebill)
  • reflect the chargeback processed by the bank (see chargeback)
  • reflect the chargeback reversal processed by the bank (see chargeback)

Operation:

Sample request:

Pre-authorize payment

Send the pre-authorization request with the collected card data.

Redirect shopper

Redirect the shopper to validate and complete the payment.

Get the payment status

Find out if the payment was successful.

OPTIONAL

Handle the receipt

Send the receipt request.

Transactions:
PA
PA
RC
RC
OPTIONAL

Manage the payment

Send the back-office payment request.

Transactions:
RF
RF
CB
CB
CR
CR
RB
RB

1. Pre-authorize payment

Initiate a server-to-server POST request with the required payment data and the shopperResultUrl that must be url-encoded. The payment details are verified with the issuer, and the funds are reserved. The response to a successful request is an id that should be stored and used in subsequent back-office operations.


2. Redirect shopper

Initiate a server-to-server request to guide the account holder through the validation and completion of the payment. To facilitate this redirection, you need to interpret the redirect object from the response of the pre-authorized payment. This redirect object, along with its parameters, will be used in conjunction with an HTML form to perform the shopper’s redirect.

  • url: The HTTPS URL for redirection, used as the form’s action attribute.
  • method: Defaults to HTTPS POST, determines form submission method.
  • parameters: Appended to URL for HTTPS GET, or included in the body for HTTPS POST. In the case of an HTTPS POST, each parameter will be a hidden input field in the HTML form.

3. Get the payment status

Once the payment request is processed, the customer is redirected to your shopperResultUrl along with a GET parameter resourcePath.

resourcePath=/v1/payments/{id}

Sample request:

You’re allowed two payment status requests per minute per transaction. However, the query endpoint provides payment status without such restrictions.

4. Handle the receipt

If you prefer to manage bank receipt confirmations yourself, initiate a server-to-server POST request for the pre-authorized payment. A receipt signifies the transfer of reserved funds from the shopper’s to the merchant’s account. However, this step is optional as the system can automatically process the receipt upon receiving a notification from the bank, depending on the payment method.

Sample request:

5. Manage the payment

Initiate a back-office server-to-server POST request over the receipt (confirmed payment) to:

  • refund either the full captured amount or a part of the captured amount (see refund)
  • rebill the processed order for additional products (see rebill)
  • reflect the chargeback processed by the bank (see chargeback)
  • reflect the chargeback reversal processed by the bank (see chargeback)

Operation:

Sample request:

See also