PHPackages                             atpay/tokens - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. atpay/tokens

ActiveLibrary[API Development](/categories/api)

atpay/tokens
============

AtPay API bindings for PHP

2.0.5(11y ago)010LGPLPHPPHP >=5.3.0

Since Dec 19Pushed 11y ago11 watchersCompare

[ Source](https://github.com/atpay/atpay_php)[ Packagist](https://packagist.org/packages/atpay/tokens)[ Docs](https://developer.atpay.com)[ RSS](/packages/atpay-tokens/feed)WikiDiscussions master Synced today

READMEChangelog (4)DependenciesVersions (10)Used By (0)

@Pay PHP Bindings
=================

[](#pay-php-bindings)

PHP implementation of @Pay's [**Token Protocol**](http://developer.atpay.com/v3/tokens/protocol/). See the [@Pay Developer Site](http://developer.atpay.com/)for additional information.

A **Token** is a value that contains information about a financial transaction (an invoice or a product sales offer, for instance). When a **Token** is sent to `transaction@processor.atpay.com` from an address associated with a **Payment Method**, it will create a **Transaction**.

There are two classes of **Token** @Pay processes - the **Targeted Token**, which should be used for sending invoices or transactions applicable to a single recipient, and the **Bulk Token**, which is suitable for email marketing lists.

An **Email Button** is a link embedded in an email message. When activated, this link opens a new outgoing email with a recipient, subject, and message body prefilled. By default this email contains one of the two token types. Clicking 'Send' delivers the email to @Pay and triggers **Transaction** processing. The sender will receive a receipt or further instructions.

Installation
------------

[](#installation)

*This library requires that the [PHP Sodium](https://github.com/alethia7/php-sodium) Extension be installed.*

### PHP Archive

[](#php-archive)

```
$ curl -O -L http://github.com/atpay/atpay_php/releases/download/2.0.2/atpay_php.phar
```

Then require `atpay_php` in your application:

```
require_once 'atpay_php.phar';        # include php archive.
```

### Composer

[](#composer)

```
{
  "require": {
    "atpay/atpay_php": "2.0.5"
  }
}
```

```
$ curl -s http://getcomposer.org/installer | php
$ php composer.phar install

```

```
require 'vendor/autoload.php';
```

Configuration
-------------

[](#configuration)

All Token generation functions require a Session object. Grab your API credentials from  (API Settings):

```
$session = new \AtPay\Session(partner_id, public_key, private_key);
```

Targeted Tokens
---------------

[](#targeted-tokens)

A **targeted** token is ideal for sending invoices or for transactions that are only applicable to a single recipient (specialized offers, etc).

The following creates a token for a 20 dollar transaction specifically for the credit card @Pay has associated with '':

```
$invoice_token = new \AtPay\Token\Targeted($session, 20, 'customer@example.com');
echo $invoice_token->to_s();
```

Note: **Targeted** tokens used to be known as **Invoice** tokens. Please use **Targeted** tokens, as **Invoice** tokens will be deprecated.

Bulk Tokens
-----------

[](#bulk-tokens)

Most merchants will be fine generating **Bulk Email Buttons** manually on the [@Pay Merchant Dashboard](https://dashboard.atpay.com), but for cases where you need to automate the generation of these messages, you can create **Bulk Tokens** without communicating directly with @Pay's servers.

A **Bulk Token** is designed for large mailing lists. You can send the same token to any number of recipients. It's ideal for 'deal of the day' type offers, or general marketing.

To create a **Bulk Token** for a 30 dollar blender:

```
$bulk_token = new \AtPay\Token\Bulk($session, 30);
echo $bulk_token->to_s();
```

If a recipient of this token attempts to purchase the product via email but hasn't configured a credit card, they'll receive a message asking them to complete their transaction. You should integrate the @Pay JS SDK on that page if you want to allow them to create a two-click email transaction in the future.

General Token Attributes
------------------------

[](#general-token-attributes)

### Auth Only

[](#auth-only)

A **Token** will trigger a funds authorization and a funds capture simultaneously. If you're shipping a physical good, or for some other reason want to delay the capture, use the `auth_only!` method to adjust this behavior:

```
$invoice_token = new \AtPay\Token\Targeted($session, 20, 'customer@example.com');
$invoice_token->auth_only();
echo $invoice_token->to_s();
```

### Expiration

[](#expiration)

A **Token** expires in 2 weeks unless otherwise specified. Trying to use the **Token**after the expiration results in a polite error message being sent to the sender. To adjust the expiration:

```
$invoice_token = new \AtPay\Token\Targeted($session, 20, 'customer@example.com');
$invoice_token->expires_in_seconds(60 * 60 * 24 * 7); // one week
echo $invoice_token->to_s();
```

### Signup Page

[](#signup-page)

When a new Customer or a Customer with expired or invalid credit card details attempts to purchase from an Email, they will be redirected to a Token's **Signup Page**, where they can enter new Credit Card details. By default @Pay will host the **Signup Page**, but you may wish to direct the Customer to a product page on your own site (Enable @Pay Card tokenization on your own page with the [@Pay JS SDK](http://developer.atpay.com/v3/javascript/)). To specify a custom URL:

```
$invoice_token = new \AtPay\Token\Targeted($session, 20, 'test@example.com');
$invoice_token->url('https://example.com/invoices/123');
echo $invoice_token->to_s();
```

#### Requesting Custom Information on a Hosted Signup Page

[](#requesting-custom-information-on-a-hosted-signup-page)

If you opt to use the **Hosted Payment Capture Page** (by not specifying a URL above), you can request further information from your Customer during the purchase on the Web. For instance, the following requests an optional Gift Message:

```
$invoice_token = new \AtPay\Token\Targeted($session, 20, 'test@example.com');
$invoice_token->request_custom_data('gift_message', true); //Input name , required (defaults to false)
echo $invoice_token->to_s();
```

#### Requesting the URL of a Hosted Signup Page

[](#requesting-the-url-of-a-hosted-signup-page)

The **Hosted Payment Capture Page** is related directly to a Token. It is created when the token is first received at `transaction@processor.atpay.com` or when the URL is requested from @Pay prior to the first use. To request the URL, you must contact @Pay's server:

```
$invoice_token = new \AtPay\Token\Targeted($session, 20, 'test@example.com');
$registration = $invoice_token->register();

echo $registration->url();
=> "https://example.secured.atpay.com/{token_identifier}"

echo $registration->short();
=> "atpay://{token_identifier}"
```

NOTE: For high traffic this solution may be inadequate. Contact @Pay for consultation.

#### Item Name

[](#item-name)

You can set an **item name** that will display on the **Hosted Payment Capture Page**

```
$invoice_token = new \AtPay\Token\Targeted($session, 20, 'test@example.com');
$invoice_token->name("A Cool Offer");
echo $invoice_token->to_s();
```

#### Item Details

[](#item-details)

You can set an **item details** that will display on the **Hosted Payment Capture Page**

```
$invoice_token = new \AtPay\Token\Targeted($session, 20, 'test@example.com');
$invoice_token->set_item_details("Lorem Ipsum ...");
echo $invoice_token->to_s();
```

#### Address Collection

[](#address-collection)

Request the **Hosted Payment Capture Page** collect any combination of shipping or billing address with `requires_shipping_address(true)` and `requires_billing_address(true)`:

```
$invoice_token = new \AtPay\Token\Targeted($session, 20, 'test@example.com');
$invoice_token->requires_billing_address(true);
$invoice_token->requires_shipping_address(true);
echo $invoice_token->to_s();

```

### Set Item Quantity

[](#set-item-quantity)

If you are using @Pay's webhook for inventory control, you can specify an initial quantity for the offer you are creating.

```
$invoice_token = new \AtPay\Token\Targeted($session, 20, 'test@example.com');
$invoice_token->set_item_quantity(3);
echo $invoice_token->to_s();
```

### Fulfillment Time

[](#fulfillment-time)

**Transaction Details** from @Pay may include an **Estimated Fulfillment Time**. @Pay expects **Auth Only** transactions when fulfillment is required. A Transaction should be Captured only when fulfillment is completed.

```
$invoice_token = new \AtPay\Token\Targeted($session, 20, 'test@example.com');
$token_token->estimated_fulfillment_days(3)      # The token is now auth-only!
email(token.to_s, receipient_address)
```

### Custom User Data

[](#custom-user-data)

**Custom User Data** is a token attribute that contains any string that you wish to get back in @Pay’s response on processing the token. It has a limit of 2500 characters.

```
$invoice_token = new \AtPay\Token\Targeted($session, 20, 'customer@example.com');
$invoice_token->custom_user_data("{foo => bar}");
echo $invoice_token->to_s();
```

Button Generation
-----------------

[](#button-generation)

The PHP client does not currently support button generation.

Full Example
------------

[](#full-example)

```