Download the PHP package apcopay/apcopay_php without Composer

ApcoPay PHP library

The ApcoPay PHP library provides the functionality to process financial transactions with the ApcoPay gateway.

Requirements

• The PHP extension cURL is required.
• A merchant account with ApcoPay. Send an email to [email protected] to set up a merchant account.

Installation

The recommended method of installation is via Packagist and Composer. Run the following command to install the package and add it as a requirement to your project's composer.json:

Alternatively, the ApcoPay PHP library can also be used by copying the contents of this repository in the project folder and using PHP require on the files as shown below.

Description

The ApcoPay PHP library

File loading

The ApcoPay PHP library files can be loaded with the following options:

Composer autoloading

For more information about composer autoloading go to https://getcomposer.org/doc/01-basic-usage.md#autoloading

Skip this step if you already have composer autoloading set up

PHP require

Initialization

The ApcoPayGateway configuration requires the following 5 parameters:

• Merchant id - The merchant id/code with ApcoPay
• Merchant password - The merchant password with ApcoPay
• Hashing secret - The hashing secret word with ApcoPay
• Notification url - The url that transaction status notifications are sent to. Should be processed as shown in the notification request example below.
• Redirection url - The url the user is redirected to after a 3DS payment. Should be processed as shown in the redirect request example below.

Initialise ApcoPayGateway example

Process transaction

TransactionRequest

• amount
• currency_code - ISO 4217 numeric code
• transaction_type - Numeric code as defined TransactionType class
• order_reference - Merchant order reference. Must not contain ||
• card_number
• card_cvv
• card_holder
• card_expiry_month
• card_expiry_year
• user_ip
• original_transaction_id - The id of a prior transaction
• user_defined_function - Must not contain ||

TransactionRequest mandatory fields

TransactionResponse

• result - Transaction result indicating the status of the transaction
• psp_id - Id of the transaction from the ApcoPay gateway
• bank_transaction_id - Id of the transaction from the bank
• date - Date of transaction. Format: yyyyMMdd
• time - Time of transaction. Format: HHmmss
• acquirer_reference
• authorization_code
• address_verification_response
• acquirer_code - Processing bank code
• user_ip
• user_defined_function
• extra_data
• card_country - Card issuing country

Result codes

Accepted transactions can have one of the following results:

• APPROVED
• CAPTURED
• VOIDED
• ENROLLED (Only Used when the Card is 3Dsecure Enrolled and needs verification with Visa/MasterCard)

Declined transaction results will vary between banks

Process transaction example

Notification request

Note: The notification response should always return HTTP status code 200 with content OK

Notification request example

Redirect request

Redirect request example

Process flow

Normal transaction flow

3DS transaction flow

1. The Apco Pay web service will verify whether the card submitted is 3Dsecure ENROLLED

   1. If the card is not enrolled for 3ds, the web service will return a normal response described in the previous section

   2. If the card is enrolled the client needs to be redirected to the verification page https://www.apsp.biz/pay/3DSFP2/verify.aspx?id=4a502205024f474a8aa1933ceac42e56 Where Id needs to be replaced with the value that was returned in the first response

2. The Client must continue the verification and submit his PIN

3. After a successful verification the client is redirected the redirection_url in the configuration

Reference transaction flow

Transaction types

Transaction types in detail

Authorisation

Authorisation - Authorisation is the first part of a two-step process

If approved, the requested amount is reserved from the credit limit of the submitted card. The reservation process is therefore used if the capturing is to be completed at a later date.

Important - The authorisation (reservation) period is approx. 7 days for credit cards and 3 days for debit cards (we recommend that you check with the bank being used). Once the reservation period has expired, it is no longer possible to capture this transaction.

Capture

Capturing is the second step of the two-step process mentioned above. A capture transaction must be preceded by an "Authorisation" transaction.

The amount to be captured must be less than or equal to the authorized amount. This also means, that partial amounts can be captured.

During the capture, an amount is debited from the customer account and credited to the merchant account.

Purchase

Purchase is a payment transaction done in a single step.

The purchase transaction handles both an authorisation and a capture at the same time.

If approved, the requested amount is debited from the customer account and credited to the merchant account.

Partial Refund

Refunds are transactions that return the payments to the customer. The refunded amount can be a part of the paid amount or the full paid amount. Refunds can relate to an existing Capture or to a Purchase. In the case of credit card payments, refunds are credited to your customer's credit card account.

Important - Refunds are not allowed for gaming merchants.

Original Credit

The original credit is used to pay out an amount greater than the amount of the original transaction.

Void Purchase, Void Credit, Void Capture and Void Authorisation

If a Void request is executed by 23:59 (bank’s time zone) of the original transaction date - the acquirer would be able to cancel this transaction.

Testing

License

The ApcoPay PHP library is open-sourced software licensed under the MIT license.