PHP

SDK Documentation

1.Introduction to the SDK

The Payer Php SDK is an all-in-one package letting you access all available web services resources in just a single integration.

Requirements:

2.Getting Started

Retrieve and install a fresh copy of the Software Development Kit for your PHP environment by typing following command from your prompt:

The last thing you’ve to do is to include the vendor autoloader module into your app to be able to access the Payer Php SDK. From the root directory the requiring should look like this:

Now the package is successfully included into your application for further usage.

3.Retrieve your Credentials

To be able to access the webservice gateway, you need to have your personal Payer Credentials ready. Your credentials is accessible through the administration portal under Settings/Account.

Note: The Payer Administration requires a valid user account. Are you missing or have lost your user details? Please contact the customer service at kundtjanst@payer.se.

4.Setup the Client

Initiate the Client object with your credentials.

The Client encapsulates the connection establishment to Payer that enables access to the webservice gateway and further usage of all available payment resources.

Example:

5.Access the Resource

All Payer webservice resources are available in the SDK as single objects e.g. Invoice, Order and Purchase. Which one you should use depends on your purpose.

A resource object may depend on specific request data. The formatting of the request object is specified under the Models section.

Note: The constructor of the Resource interface depends on an instance of the Payer Client (gateway).

5.1.Purchase

5.1.1.Perform a Purchase

The Purchase chain comprises three steps: Initiate the payment, create an Authorize Callback Resource and create a Settlement Callback Resource.

5.1.1.1.Initiate the payment

5.1.1.1.1.Embedded client

Setup the request object data and pass it as an argument into the payment initialization function.

Then initiate the payment by calling the create function with the request object according to the expected data format.

This call will trigger a POST inquiry to Payer and the payment dialogue HTML page will be returned in response upon success.

Example:


Request Object

Name Type Max Description
payment object - See Models 1.8
purchase object - See Models 1.10

5.1.1.1.2.Manual request

This function inherits from 5.1.1.1.1 Embedded client but differentiates in the way that it skips the last client build step. Instead this method is focused on delivery the raw data back to the SDK user.

A better-suited solution if more demands are placed on flexibility and more control over the payment flow.

The returned data refers to match the attributes covered in the Perform the HTTP Request section during the Custom Integration.

Example:


Request Object

Name Type Max Description
payment object - See Models 1.8
purchase object - See Models 1.10

5.1.1.2.Handle Callbacks

During the payment session a total of two callbacks will be sent back to the shop. The callbacks consists various parameters in the url (HTTP GET) for further order state updates at the merchant.

The two different callback types are:

To be able to do a full purchase through Payer, you have to create these callback resource endpoints at your side. The SDK is providing two ways to achieve this.

A more detailed explanation of the callback handling can be found here.

Simple Resource

The simplest way to do this is by creating a resource endpoint for each callback type using the functions in the Purchase object:

  • createAuthorizeResource
  • createSettlementResource

Notice that these functions will just validate that the callbacks is coming from Payer and if it does, your shop will signal the successful reception. In other words, these methods do not take care of any further order state updates in your shop.

Authorize Example

Note: The url to the Authorize Callback Resource endpoint must be specified in the request data object when initiating the payment.

Settlement Example

Note: The url to the Settlement Callback Resource endpoint must be specified in the request data object when initiating the payment.

Request Object

Name Type Max Description
proxy array - An array of valid IP addresses of the callback source (optional)

Read more about the source address validation here.

 

Custom Resource

The secondary way is preferred if you want to handle some custom logic that depends on the callback data such as order status updates or e.g. handling of ticket reservations.

Example:

Note: The url to the Callback Resource endpoint must be specified in the request data object when initiating the payment.

All available parameters in the callback url is described here

5.1.2.Recurring Payment

The Recurring payment chain comprises three steps: Store Customer, Fetch the Recurring Token and Recurring Debit.

5.1.2.1.Store Customer

To be able to charge the customer during recurring debit, the customer payment details has to be stored initially by initiating a Purchase with the storage flag set to ‘true’ in the payment options.

Example:

5.1.2.2.Fetching the Recurring Token

The token is caught up in the Authorize Callback Resource for further management and database storage.

Example:

5.1.2.3.Debit

Use the fetched recurring token to make the final debit.

Example:


Request Object

Name Type Max Description
recurring_token string - See Section 5.1.2.2
description string - Adds a transaction description
amount double - The debit amount
vat_percentage double - The debit amount vat in percentage
currency string - The currency (optional)

The default value is set to ‘SEK’.
reference_id string - Corresponds to the merchants reference id

Response Object

Name Type Description
transaction_id int The id of the created transaction

5.1.3.Refund

Perform a refund of a transaction by a specific amount and vat percentage.

Example:

Note: Unfortunately, the transaction id is only available through the invoice status object and could therefore not be fetched for other payment methods such as card or bank.


Request Object

Name Type Max Description
transaction_id int - The id of the transaction to refund
reason string - Add a reason to the refund
amount double - The refund amount
vat_percentage double - The refund amount vat in percentage

5.1.4.Settlement

Perform a settlement on a pending, only authorized, payment.

Example:


Request Object

Name Type Max Description
settlement_id string - Contact Payer for more information about how this value can be accessed.
amount double - The final settle amount

5.2.Order

5.2.1.Create a new Order

This will create a pending order in Payers system.

Example:


Request Object

Name Type Max Description
reference_id string - Sets the merchants reference_id (optional)

This will be auto-generated by Payer if empty.
description string - Sets a comprehensive description on the order (optional)
customer object - See Models 1.3
items objects[] - See Models 1.4
currency string - Sets the currency of the order (optional)

The default value is set to ‘SEK’.
test_mode bool - Defines whether the order should be created in production mode or not
message string - Sets a message on the order (optional)
client_ip string - The IP address of the client
charset string - Sets the order charset (optional)

The default value is set to ‘ISO-8859-1’.
options object - See Models 1.2


Response Object

Name Type Description
order_id int The id of the created order

5.2.2.Commit Order

Confirms and transfers the order into an invoice.

Example:

Note: An invoice may be either activated directly during the commitment or just transferred to an non-activated invoice. What’s true in your case may vary and depends on the supplier and/or what has been determined in your agreement. Please contact the Payer Customer Service for more information.


Request Object

Name Type Max Description
reference_id string - The merchants order reference id (optional)
order_id int - The internal Payer id of the order (optional)

Note: If both parameters are set at the same time, the reference id will be used.


Response Object

Name Type Description
invoice_number string The identification number of the created invoice

5.2.3.Get the Order Status

Returns a status object for the specified order. The object describes the current state of the order.

Example:


Request Object

Name Type Max Description
order_id int - The id of the order to fetch

Response Object

Name Type Description
status string The current order state
create_date string The time when the order was created
order_number string The identification number of the order
order_total double The origin order amount
delivered_total double The corresponding amount delivered to the consumer
delivered_vat double The corresponding vat amount delivered to the consumer
options string Defines a string of extended options
customer object See Models 1.6
invoice object See Models 1.7

5.3.Invoice

5.3.1.Activate Invoice

Confirm the invoice and make it ready for distribution.

Furthermore, this call will set a initial due date on the invoice header and make it available for the supplier.

Example:


Request Object

Name Type Max Description
invoice_number string - The identification number of the invoice to activate
options object - See Models 1.2 (optional)

Response Object

Name Type Description
invoice_number string The identification number of the activated invoice

5.3.2.Get the Invoice Status

Returns a status object for the specified invoice. The object describes the current state of the invoice.

Example:


Request Object

Name Type Max Description
invoice_number string - The identification number of the invoice to be fetched

Response Object

Name Type Description
order_number string The identification number of the origin order
transaction_id int The id of the origin payment transaction
customer object See Models 1.3
total_amount double The origin amount
rounding_amount double The rounding amount from the origin
to_pay_amount double The outstanding amount to pay from the origin
invoice_date string The time when the invoice was created
due_date string The time when the invoice expires
paid_date string The time when the invoice was fully paid
events objects[] See Models 1.4
options string A string of extended options
delivery_type string The delivery type of the distribution

5.3.3.Send Invoice

Requests a copy of the invoice to be sent via either print or e-mail.

This will be placed into the distribution queue and handled as an asynchronous job.

Example:


Request Object

Name Type Max Description
invoice_number string - The identification number of the invoice to be sent to the consumer
options object - See Model 1.2 (optional)

Response Object

Name Type Description
process_id int The id of the distribution process

5.3.4.Template Binding

Binds an invoice to a specific template entry. This will override the default template in the distribution.

Example:


Request Object

Name Type Max Description
invoice_number string - The identification number of the invoice to be bounded
template_entry_id int - The id of the template entry that should be bounded to the invoice.

Section 5.3.5 shows an example of how this value can be fetched.

Response Object

Name Type Description
template_entry_binding_id int The bounding entry id
create_date string The entry creation time

5.3.5.Get Template Entries

Returns a list with active template entries that has been created by the merchant.

Example:

Note: A Template Entry may be created from the Payer Administration.


Response Object

Name Type Description
template_entries objects[] See Model 1.11

5.4.Session

5.4.1.Challenge Response

Creates a unique challenge token that may be used by a third-party such a web client. The token is used to allow session access during a request.

Example:


Response Object

Name Type Description
status string The status of the request
challenge_token string A valid third-party session token

5.5.Miscellaneous

5.5.1.Get Address

Fetches the address details about the consumer. Used in e.g. the checkout to improve the shopping experience additionally.

Example:


Request Object

Name Type Max Description
identity_number string - The SSN or organisation number
zip_code string - The registered zip code
challenge_token string - See Section 5.4.1

Response Object

Name Type Description
status string The status of the request
identity_number string The SSN or organisation number
organisation string The organisation name
first_name string The first name
last_name string The last name
address_1 string The primary address
address_2 string The secondary address
zip_code string The zip code
city string The city
country string The country

6.Models

The models are reusable structure definitions that defines how the specific ingoing data object should be formatted in the communication with Payer.

What model you may use in your request is specified in the Request Object for each resource access section.

The complete list including all SDK model definitions can be found here.

7.Exceptions

All internal errors are handled and encapsulated as several exception classes that inherits from the parent class PayerException.

Any Exception that occurs during the runtime can be caught up persuent to following example:

PayerException
The parent class that inherits from the Exception class.

HttpTransportException
Thrown during Http Transport failure.

InvalidRequestException
Thrown if the input data object mismatches the requested model.

ValidationException
Thrown if any input data is invalid.

WebserviceException
Thrown if any error occurs during the Webservice resource access.

Suggest Edit