logo
Documentation
NAV
cURL Java PHP Python Ruby

Guides

Overview

These guides provide a collection of resources for utilizing the Payline API and its client libraries. We offer a number of client libraries for interfacing with the API, and you can view example code snippets for each in the dark area to the right.

  1. Authentication: A quick guide on how to properly authenticate and interface with the API.

  2. Getting Started: A step-by-step guide demonstrating the basic workflow of charging a card. This guide will walk you through provisioning merchant accounts, tokenizing cards, charging those cards, and finally settling (i.e. payout) those funds out to your merchants.

  3. Embedded Tokenization: This guide explains how to properly tokenize cards in production via our embedded iframe.

Authentication

# With CURL, just supply your username as basic auth (-u) in the header of each request as follows:

curl https://api-test.payline.io/ \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3

/*
Add the following to your pom.xml (Maven file):

<dependency>
  <groupId>io.payline.payments.processing.client</groupId>
  <artifactId>payline-data</artifactId>
  <version>${version}</version>
</dependency>

...

<repositories>
  <repository>
    <id>oss-snapshots</id>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

*/

import io.payline.payments.processing.client.ProcessingClient;
import io.payline.payments.processing.client.model.*;

//...

public static void main(String[] args) {

  ProcessingClient client = new ProcessingClient("https://api-test.payline.io");
  client.setupUserIdAndPassword("US7gYxecvqqmmk3Qyu94YAwk", "2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3");

//...

<?php
// Download the PHP Client here: https://github.com/Payline/payline-php

require_once('vendor/autoload.php');
require(__DIR__ . '/src/Payline/Settings.php');

Payline\Settings::configure([
  "root_url" => 'https://api-test.payline.io',
  "username" => 'US7gYxecvqqmmk3Qyu94YAwk',
  "password" => '2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3']
  );

require(__DIR__ . '/src/Payline/Bootstrap.php');
Payline\Bootstrap::init();



# To install the python client run the command below from your terminal:
# pip install payline

import payline

from payline.config import configure
configure(root_url="https://api-test.payline.io", auth=("US7gYxecvqqmmk3Qyu94YAwk", "2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3"))

# To download the Ruby gem:
# gem install payline-data

require 'payline'

Payline.configure(
    :root_url => 'https://api-test.payline.io',
    :user=>'US7gYxecvqqmmk3Qyu94YAwk',
    :password => '2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3'
)

To communicate with the Payline API you’ll need to authenticate your requests via http basic access authentication with a username and password, which you can locate in your dashboard. If you do not have a dashboard feel free to test the API with the credentials below:

Your Application is a resource that represents your web app. In other words, any web service that connects buyers (i.e. customers) and sellers (i.e. merchants).

API Endpoints

We provide two distinct base urls for making API requests depending on whether you would like to utilize the sandbox or production environments. These two environments are completely seperate and share no information, including API credentials. For testing please use the Staging API and when you are ready to process live transactions use the Production endpoint.

Getting Started

Step 1: Create an Identity for a Merchant

curl https://api-test.payline.io/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "tags": {
          "Studio Rating": "4.7"
      }, 
      "entity": {
          "last_name": "Sunkhronos", 
          "max_transaction_amount": 12000000, 
          "has_accepted_credit_cards_previously": true, 
          "default_statement_descriptor": "Prestige World Wide", 
          "personal_address": {
              "city": "San Mateo", 
              "country": "USA", 
              "region": "CA", 
              "line2": "Apartment 7", 
              "line1": "741 Douglass St", 
              "postal_code": "94114"
          }, 
          "incorporation_date": {
              "year": 1978, 
              "day": 27, 
              "month": 6
          }, 
          "business_address": {
              "city": "San Mateo", 
              "country": "USA", 
              "region": "CA", 
              "line2": "Apartment 8", 
              "line1": "741 Douglass St", 
              "postal_code": "94114"
          }, 
          "ownership_type": "PRIVATE", 
          "first_name": "dwayne", 
          "title": "CEO", 
          "business_tax_id": "123456789", 
          "doing_business_as": "Prestige World Wide", 
          "principal_percentage_ownership": 50, 
          "email": "user@example.org", 
          "mcc": "0742", 
          "phone": "1234567890", 
          "business_name": "Prestige World Wide", 
          "tax_id": "123456789", 
          "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP", 
          "business_phone": "+1 (408) 756-4497", 
          "dob": {
              "year": 1978, 
              "day": 27, 
              "month": 6
          }, 
          "url": "www.PrestigeWorldWide.com", 
          "annual_card_volume": 12000000
      }
  }'


import io.payline.payments.processing.client.model.Address;
import io.payline.payments.processing.client.model.BankAccountType;
import io.payline.payments.processing.client.model.BusinessType;
import io.payline.payments.processing.client.model.Date;
import io.payline.payments.processing.client.model.Entity;
import io.payline.payments.processing.client.model.Identity;

Identity identity = client.identitiesClient().save(
  Identity.builder()
    .entity(
      Entity.builder()
        .title("CEO")
        .firstName("dwayne")
        .lastName("Sunkhronos")
        .email("user@example.org")
        .businessName("business inc")
        .businessType(BusinessType.LIMITED_LIABILITY_COMPANY)
        .doingBusinessAs("doingBusinessAs")
        .phone("1234567890")
        .businessPhone("+1 (408) 756-4497")
        .taxId("123456789")
        .businessTaxId("123456789")
        .personalAddress(
          Address.builder()
            .line1("741 Douglass St")
            .line2("Apartment 7")
            .city("San Mateo")
            .region("CA")
            .postalCode("94114")
            .country("USA")
            .build()
        )
        .businessAddress(
          Address.builder()
            .line1("741 Douglass St")
            .line2("Apartment 7")
            .city("San Mateo")
            .region("CA")
            .postalCode("94114")
            .country("USA")
            .build()
        )
        .dob(Date.builder()
          .day(27)
          .month(5)
          .year(1978)
          .build()
        )
        .settlementCurrency("USD")
        .settlementBankAccount(BankAccountType.CORPORATE)
        .maxTransactionAmount(1000l)
        .mcc(7399)
        .url("http://sample-entity.com")
        .annualCardVolume(100)
        .defaultStatementDescriptor("Business Inc")
        .incorporationDate(Date.builder()
          .day(1)
          .month(12)
          .year(2012)
          .build()
        )
        .principalPercentageOwnership(51)
        .ownershipType("PRIVATE")
        .hasAcceptedCreditCardsPreviously(false)
        .build()
    )
    .build()
);

<?php
use Payline\Resources\Identity;

$identity = new Identity(
  array(
      "tags"=> array(
          "Studio Rating"=> "4.7"
      ), 
      "entity"=> array(
          "last_name"=> "Sunkhronos", 
          "max_transaction_amount"=> 12000000, 
          "has_accepted_credit_cards_previously"=> true, 
          "default_statement_descriptor"=> "Prestige World Wide", 
          "personal_address"=> array(
              "city"=> "San Mateo", 
              "country"=> "USA", 
              "region"=> "CA", 
              "line2"=> "Apartment 7", 
              "line1"=> "741 Douglass St", 
              "postal_code"=> "94114"
          ), 
          "incorporation_date"=> array(
              "year"=> 1978, 
              "day"=> 27, 
              "month"=> 6
          ), 
          "business_address"=> array(
              "city"=> "San Mateo", 
              "country"=> "USA", 
              "region"=> "CA", 
              "line2"=> "Apartment 8", 
              "line1"=> "741 Douglass St", 
              "postal_code"=> "94114"
          ), 
          "ownership_type"=> "PRIVATE", 
          "first_name"=> "dwayne", 
          "title"=> "CEO", 
          "business_tax_id"=> "123456789", 
          "doing_business_as"=> "Prestige World Wide", 
          "principal_percentage_ownership"=> 50, 
          "email"=> "user@example.org", 
          "mcc"=> "0742", 
          "phone"=> "1234567890", 
          "business_name"=> "Prestige World Wide", 
          "tax_id"=> "123456789", 
          "business_type"=> "INDIVIDUAL_SOLE_PROPRIETORSHIP", 
          "business_phone"=> "+1 (408) 756-4497", 
          "dob"=> array(
              "year"=> 1978, 
              "day"=> 27, 
              "month"=> 6
          ), 
          "url"=> "www.PrestigeWorldWide.com", 
          "annual_card_volume"=> 12000000
      )
  )
);
$identity = $identity->save();



from payline.resources import Identity

identity = Identity(**
  {
      "tags": {
          "Studio Rating": "4.7"
      }, 
      "entity": {
          "last_name": "Sunkhronos", 
          "max_transaction_amount": 12000000, 
          "has_accepted_credit_cards_previously": True, 
          "default_statement_descriptor": "Prestige World Wide", 
          "personal_address": {
              "city": "San Mateo", 
              "country": "USA", 
              "region": "CA", 
              "line2": "Apartment 7", 
              "line1": "741 Douglass St", 
              "postal_code": "94114"
          }, 
          "incorporation_date": {
              "year": 1978, 
              "day": 27, 
              "month": 6
          }, 
          "business_address": {
              "city": "San Mateo", 
              "country": "USA", 
              "region": "CA", 
              "line2": "Apartment 8", 
              "line1": "741 Douglass St", 
              "postal_code": "94114"
          }, 
          "ownership_type": "PRIVATE", 
          "first_name": "dwayne", 
          "title": "CEO", 
          "business_tax_id": "123456789", 
          "doing_business_as": "Prestige World Wide", 
          "principal_percentage_ownership": 50, 
          "email": "user@example.org", 
          "mcc": "0742", 
          "phone": "1234567890", 
          "business_name": "Prestige World Wide", 
          "tax_id": "123456789", 
          "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP", 
          "business_phone": "+1 (408) 756-4497", 
          "dob": {
              "year": 1978, 
              "day": 27, 
              "month": 6
          }, 
          "url": "www.PrestigeWorldWide.com", 
          "annual_card_volume": 12000000
      }
  }).save()

identity = Payline::Identity.new(
  {
      "tags"=> {
          "Studio Rating"=> "4.7"
      }, 
      "entity"=> {
          "last_name"=> "Sunkhronos", 
          "max_transaction_amount"=> 12000000, 
          "has_accepted_credit_cards_previously"=> true, 
          "default_statement_descriptor"=> "Prestige World Wide", 
          "personal_address"=> {
              "city"=> "San Mateo", 
              "country"=> "USA", 
              "region"=> "CA", 
              "line2"=> "Apartment 7", 
              "line1"=> "741 Douglass St", 
              "postal_code"=> "94114"
          }, 
          "incorporation_date"=> {
              "year"=> 1978, 
              "day"=> 27, 
              "month"=> 6
          }, 
          "business_address"=> {
              "city"=> "San Mateo", 
              "country"=> "USA", 
              "region"=> "CA", 
              "line2"=> "Apartment 8", 
              "line1"=> "741 Douglass St", 
              "postal_code"=> "94114"
          }, 
          "ownership_type"=> "PRIVATE", 
          "first_name"=> "dwayne", 
          "title"=> "CEO", 
          "business_tax_id"=> "123456789", 
          "doing_business_as"=> "Prestige World Wide", 
          "principal_percentage_ownership"=> 50, 
          "email"=> "user@example.org", 
          "mcc"=> "0742", 
          "phone"=> "1234567890", 
          "business_name"=> "Prestige World Wide", 
          "tax_id"=> "123456789", 
          "business_type"=> "INDIVIDUAL_SOLE_PROPRIETORSHIP", 
          "business_phone"=> "+1 (408) 756-4497", 
          "dob"=> {
              "year"=> 1978, 
              "day"=> 27, 
              "month"=> 6
          }, 
          "url"=> "www.PrestigeWorldWide.com", 
          "annual_card_volume"=> 12000000
      }
  }).save

Example Response:

{
  "id" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "entity" : {
    "title" : "CEO",
    "first_name" : "dwayne",
    "last_name" : "Sunkhronos",
    "email" : "user@example.org",
    "business_name" : "Prestige World Wide",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "doing_business_as" : "Prestige World Wide",
    "phone" : "1234567890",
    "business_phone" : "+1 (408) 756-4497",
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "business_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 8",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "mcc" : "0742",
    "dob" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "max_transaction_amount" : 12000000,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : "www.PrestigeWorldWide.com",
    "annual_card_volume" : 12000000,
    "has_accepted_credit_cards_previously" : true,
    "incorporation_date" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "principal_percentage_ownership" : 50,
    "short_business_name" : null,
    "ownership_type" : "PRIVATE",
    "tax_id_provided" : true,
    "business_tax_id_provided" : true,
    "default_statement_descriptor" : "Prestige World Wide"
  },
  "tags" : {
    "Studio Rating" : "4.7"
  },
  "created_at" : "2017-04-24T20:22:41.83Z",
  "updated_at" : "2017-04-24T20:22:41.83Z",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "verifications" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/verifications"
    },
    "merchants" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/merchants"
    },
    "settlements" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/settlements"
    },
    "authorizations" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/authorizations"
    },
    "transfers" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/transfers"
    },
    "payment_instruments" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/payment_instruments"
    },
    "disputes" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/disputes"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    }
  }
}

Before we can begin charging cards we’ll need to provision a Merchant account for your seller. This requires 3-steps, which we’ll go into greater detail in the next few sections:

  1. First, create an Identity resource with the merchant’s underwriting and identity verification information

    POST https://api-test.payline.io/identities/

  2. Second, create a Payment Instrument representing the merchant’s bank account where processed funds will be settled (i.e. deposited)

    POST https://api-test.payline.io/payment_instruments/

  3. Finally, provision the Merchant account

    POST https://api-test.payline.io/identities/:IDENTITY_ID/merchants

Let’s start with the first step by creating an Identity resource. Each Identity represents either a person or a business. We use this resource to associate cards and payouts. This structure makes it simple to manage and reconcile payment instruments and payout history. Accounting of funds is done using the Identity so it’s recommended to have an Identity per recipient of funds. Additionally, the Identity resource is optionally used to collect KYC information.

You’ll want to store the ID of the newly created Identity resource for reference later.

HTTP Request

POST https://api-test.payline.io/identities

Business-specific Request Arguments

Field Type Description
business_name string, required Merchant’s full legal business name (If INDIVIDUAL_SOLE_PROPRIETORSHIP, please input first name, Full legal last name and middle initial; max 120 characters)
doing_business_as string, required Alternate name of the business. If no other name is used please use the same value for business_name (max 60 characters)
business_type string, required Please select one of the following values: INDIVIDUAL_SOLE_PROPRIETORSHIP, CORPORATION, LIMITED_LIABILITY_COMPANY, PARTNERSHIP, ASSOCIATION_ESTATE_TRUST, TAX_EXEMPT_ORGANIZATION, INTERNATIONAL_ORGANIZATION, GOVERNMENT_AGENCY
business_tax_id string, required Nine digit Tax Identification Number (TIN), Employer Identification Number (EIN) or if the business_type is INDIVIDUAL_SOLE_PROPRIETORSHIP and a Tax ID is not available, the principal’s Social Security Number (SSN)
url string, required Merchant’s publicly available website (max 100 characters)
business_phone string, required Customer service phone number where the merchant can be reached (max 10 characters)
incorporation_date object, required Date company was founded (See below for a full list of the child attributes)
business_address object, required Primary address for the legal entity (Full description of child attributes below)
ownership_type string, required Values can be either PUBLIC to indicate a publicly traded company or PRIVATE for privately held businesses

Principal-specific Request Arguments

(i.e. authorized representative or primary contact responsible for the account)

Field Type Description
first_name string, required Full legal first name of the merchant’s principal representative (max 20 characters)
last_name string, required Full legal last name of the merchant’s principal representative (max 20 characters)
title string, required Principal’s corporate title or role (i.e. Chief Executive Officer, CFO, etc.; max 60 characters)
principal_percentage_ownership integer, required Percentage of company owned by the principal (min 0; max 100)
tax_id string, required Nine digit Social Security Number (SSN) for the principal
dob object, required Principal’s date of birth (Full description of child attributes below)
phone string, required Principal’s phone number (max 10 characters)
email string, required Principal’s email address where they can be reached (max 100 characters)
personal_address object, required Principal’s personal home address. This field is used for identity verification purposes (Full description of child attributes below)

Processing-specific Request Arguments

Field Type Description
default_statement_descriptor string, required Billing descriptor displayed on the buyer’s bank or card statement (Length must be between 1 and 20 characters)
annual_card_volume integer, required Approximate annual credit card sales expected to be processed in cents by this merchant (max 23 characters)
max_transaction_amount integer, required Maximum amount that can be transacted for a single transaction in cents (max 12 characters)
mcc string, required Merchant Category Code (MCC) that this merchant will be classified under
has_accepted_credit_cards_previously boolean, optional Defaults to false if not passed

Address-object Request Arguments

Field Type Description
line1 string, required First line of the address (max 60 characters)
line2 string, optional Second line of the address (max 60 characters)
city string, required City (max 20 characters)
region string, required 2-letter State code
postal_code string, required Zip or Postal code (max 7 characters)
country string, required 3-Letter Country code

Incorporation Date-object Request Arguments

Field Type Description
day integer, required Day business was incorporated (between 1 and 31)
month integer, required Month business was incorporated (between 1 and 12)
year integer, required Year business was incorporated (4-digit)

DOB-object Request Arguments

Field Type Description
day integer, required Day of birth (between 1 and 31)
month integer, required Month of birth (between 1 and 12)
year integer, required Year of birth (4-digit)

Step 2: Tokenize a Bank Account for Funding your Merchant

curl https://api-test.payline.io/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "account_type": "SAVINGS", 
      "name": "Fran Lemke", 
      "tags": {
          "Bank Account": "Company Account"
      }, 
      "country": "USA", 
      "bank_code": "123123123", 
      "account_number": "123123123", 
      "type": "BANK_ACCOUNT", 
      "identity": "ID8dfS5cFQYW2Ckee7BvVR4R"
  }'



import io.payline.payments.processing.client.model.BankAccount;
import io.payline.payments.processing.client.model.Name;

BankAccount bankAccount = client.bankAccountsClient().save(
    BankAccount.builder()
      .name(Name.parse("Joe Doe"))
      .identity(identity.getId())  //  or use "ID8dfS5cFQYW2Ckee7BvVR4R"
      .accountNumber("84012312415")
      .bankCode("840123124")
      .accountType(BankAccountType.SAVINGS)
      .companyName("company name")
      .country("USA")
      .currency("USD")
      .build()
);


<?php
use Payline\Resources\Identity;
use Payline\Resources\BankAccount;

$identity = Identity::retrieve('ID8dfS5cFQYW2Ckee7BvVR4R');
$bank_account = new BankAccount(
  array(
      "account_type"=> "SAVINGS", 
      "name"=> "Fran Lemke", 
      "tags"=> array(
          "Bank Account"=> "Company Account"
      ), 
      "country"=> "USA", 
      "bank_code"=> "123123123", 
      "account_number"=> "123123123", 
      "type"=> "BANK_ACCOUNT", 
      "identity"=> "ID8dfS5cFQYW2Ckee7BvVR4R"
  ));
$bank_account = $identity->createBankAccount($bank_account);


from payline.resources import BankAccount

bank_account = BankAccount(**
  {
      "account_type": "SAVINGS", 
      "name": "Fran Lemke", 
      "tags": {
          "Bank Account": "Company Account"
      }, 
      "country": "USA", 
      "bank_code": "123123123", 
      "account_number": "123123123", 
      "type": "BANK_ACCOUNT", 
      "identity": "ID8dfS5cFQYW2Ckee7BvVR4R"
  }).save()

bank_account = Payline::BankAccount.new(
  {
      "account_type"=> "SAVINGS", 
      "name"=> "Fran Lemke", 
      "tags"=> {
          "Bank Account"=> "Company Account"
      }, 
      "country"=> "USA", 
      "bank_code"=> "123123123", 
      "account_number"=> "123123123", 
      "type"=> "BANK_ACCOUNT", 
      "identity"=> "ID8dfS5cFQYW2Ckee7BvVR4R"
  }).save

Example Response:

{
  "id" : "PIhGEt5UWQXxrvNba8bc6jxg",
  "fingerprint" : "FPR-1215770130",
  "tags" : {
    "Bank Account" : "Company Account"
  },
  "bank_code" : "123123123",
  "country" : "USA",
  "masked_account_number" : "XXXXX3123",
  "name" : "Fran Lemke",
  "account_type" : "SAVINGS",
  "created_at" : "2017-04-24T20:22:45.94Z",
  "updated_at" : "2017-04-24T20:22:45.94Z",
  "instrument_type" : "BANK_ACCOUNT",
  "type" : "BANK_ACCOUNT",
  "currency" : "USD",
  "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIhGEt5UWQXxrvNba8bc6jxg"
    },
    "authorizations" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIhGEt5UWQXxrvNba8bc6jxg/authorizations"
    },
    "identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "transfers" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIhGEt5UWQXxrvNba8bc6jxg/transfers"
    },
    "verifications" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIhGEt5UWQXxrvNba8bc6jxg/verifications"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    }
  }
}

Now that we’ve created an Identity for our merchant, we’ll need to add a bank account where funds will be disbursed (i.e. their funding account).

In the API, bank accounts – as well as credit cards – are represented by the Payment Instrument resource.

To classify the Payment Instrument as a bank account you’ll need to pass BANK_ACCOUNT in the type field of your request, and you’ll also want to pass the ID of the Identity that you created in the last step via the identity field to properly associate it with your merchant.

HTTP Request

POST https://api-test.payline.io/payment_instruments

Request Arguments

Field Type Description
account_number string, required Bank account number
bank_code string, required Bank routing number
type string, required Type of Payment Instrument (for bank accounts use BANK_ACCOUNT)
identity string, required ID for the Identity resource which the account is associated
account_type string, required Either CHECKING or SAVINGS
name string, required Account owner’s full name (max 40 characters)

Step 3: Provision Merchant Account

curl https://api-test.payline.io/identities/ID8dfS5cFQYW2Ckee7BvVR4R/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "processor": null, 
      "tags": {
          "key_2": "value_2"
      }
  }'
import io.payline.payments.processing.client.model.Merchant;

Merchant merchant = identity.provisionMerchantOn(Merchant.builder().build());

<?php
use Payline\Resources\Identity;
use Payline\Resources\Merchant;

$identity = Identity::retrieve('ID8dfS5cFQYW2Ckee7BvVR4R');
$merchant = $identity->provisionMerchantOn(new Merchant());


from payline.resources import Identity
from payline.resources import Merchant

identity = Identity.get(id="ID8dfS5cFQYW2Ckee7BvVR4R")
merchant = identity.provision_merchant_on(Merchant())
identity = Payline::Identity.retrieve(:id=>"ID8dfS5cFQYW2Ckee7BvVR4R")

merchant = identity.provision_merchant

Example Response:

{
  "id" : "MUmCHstoi1n9eERezsZuzxa6",
  "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "verification" : "VI4Bcyya4EAGiZhCkJnWmbtY",
  "merchant_profile" : "MPgm1QRhcy8tY144m5vC3tNs",
  "processor" : "DUMMY_V1",
  "processing_enabled" : false,
  "settlement_enabled" : false,
  "tags" : { },
  "created_at" : "2017-04-24T20:22:47.31Z",
  "updated_at" : "2017-04-24T20:22:47.31Z",
  "onboarding_state" : "PROVISIONING",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/merchants/MUmCHstoi1n9eERezsZuzxa6"
    },
    "identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "verifications" : {
      "href" : "https://api-test.payline.io:443/merchants/MUmCHstoi1n9eERezsZuzxa6/verifications"
    },
    "merchant_profile" : {
      "href" : "https://api-test.payline.io:443/merchant_profiles/MPgm1QRhcy8tY144m5vC3tNs"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "verification" : {
      "href" : "https://api-test.payline.io:443/verifications/VI4Bcyya4EAGiZhCkJnWmbtY"
    }
  }
}

Now that we’ve associated a Payment Instrument with our seller’s Identity we’re ready to provision a Merchant account. This is the last step before you can begin processing on their behalf. Luckily you’ve already done most of the heavy lifting. Just make one final POST request, and you’ll be returned a Merchant resource. Take a second to inspect this newly created resource, particularly the onboarding_state, which can have 3 potential states that indicate its ability to process and settle funds:

  1. PROVISIONING: Request is pending (state will typically change after two minutes)

    • processing_enabled: False
    • settlement_enabled: False
  2. APPROVED: Merchant has been approved and can begin processing

    • processing_enabled: True
    • settlement_enabled: True
  3. REJECTED: Merchant was rejected by the processor either because the collected information was invalid or it failed one of a number of regulatory and/or compliance checks (e.g. KYC, OFAC or MATCH)

    • processing_enabled: False
    • settlement_enabled: False

HTTP Request

POST https://api-test.payline.io/identities/:IDENTITY_ID/merchants

URL Parameters

Parameter Description
:IDENTITY_ID ID of the Identity

Step 4: Create an Identity for a Buyer


curl https://api-test.payline.io/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "tags": {
          "key": "value"
      }, 
      "entity": {
          "phone": "7145677613", 
          "first_name": "Alex", 
          "last_name": "Serna", 
          "email": "therock@gmail.com", 
          "personal_address": {
              "city": "San Mateo", 
              "country": "USA", 
              "region": "CA", 
              "line2": "Apartment 7", 
              "line1": "741 Douglass St", 
              "postal_code": "94114"
          }
      }
  }'


import io.payline.payments.processing.client.model.Identity;

Identity buyerIdentity = client.identitiesClient().save(
  Identity.builder()
    .entity(
      Entity.builder()
        .firstName("dwayne")
        .lastName("Sunkhronos")
        .email("user@example.org")
        .build()
    )
    .build()
);
<?php
use Payline\Resources\Identity;

$identity = new Identity(
  array(
      "tags"=> array(
          "key"=> "value"
      ), 
      "entity"=> array(
          "phone"=> "7145677613", 
          "first_name"=> "Alex", 
          "last_name"=> "Serna", 
          "email"=> "therock@gmail.com", 
          "personal_address"=> array(
              "city"=> "San Mateo", 
              "country"=> "USA", 
              "region"=> "CA", 
              "line2"=> "Apartment 7", 
              "line1"=> "741 Douglass St", 
              "postal_code"=> "94114"
          )
      )
  ));
$identity = $identity->save();



from payline.resources import Identity

identity = Identity(**
  {
      "tags": {
          "key": "value"
      }, 
      "entity": {
          "phone": "7145677613", 
          "first_name": "Alex", 
          "last_name": "Serna", 
          "email": "therock@gmail.com", 
          "personal_address": {
              "city": "San Mateo", 
              "country": "USA", 
              "region": "CA", 
              "line2": "Apartment 7", 
              "line1": "741 Douglass St", 
              "postal_code": "94114"
          }
      }
  }).save()

identity = Payline::Identity.new(
  {
      "tags"=> {
          "key"=> "value"
      }, 
      "entity"=> {
          "phone"=> "7145677613", 
          "first_name"=> "Alex", 
          "last_name"=> "Serna", 
          "email"=> "therock@gmail.com", 
          "personal_address"=> {
              "city"=> "San Mateo", 
              "country"=> "USA", 
              "region"=> "CA", 
              "line2"=> "Apartment 7", 
              "line1"=> "741 Douglass St", 
              "postal_code"=> "94114"
          }
      }
  }).save

Example Response:

{
  "id" : "IDpBkS8wBTAticFPHs4gJnp2",
  "entity" : {
    "title" : null,
    "first_name" : "Alex",
    "last_name" : "Serna",
    "email" : "therock@gmail.com",
    "business_name" : null,
    "business_type" : null,
    "doing_business_as" : null,
    "phone" : "7145677613",
    "business_phone" : null,
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "business_address" : null,
    "mcc" : null,
    "dob" : null,
    "max_transaction_amount" : 0,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : null,
    "annual_card_volume" : 0,
    "has_accepted_credit_cards_previously" : false,
    "incorporation_date" : null,
    "principal_percentage_ownership" : null,
    "short_business_name" : null,
    "ownership_type" : null,
    "tax_id_provided" : false,
    "business_tax_id_provided" : false,
    "default_statement_descriptor" : null
  },
  "tags" : {
    "key" : "value"
  },
  "created_at" : "2017-04-24T20:22:48.23Z",
  "updated_at" : "2017-04-24T20:22:48.23Z",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2"
    },
    "verifications" : {
      "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/verifications"
    },
    "merchants" : {
      "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/merchants"
    },
    "settlements" : {
      "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/settlements"
    },
    "authorizations" : {
      "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/authorizations"
    },
    "transfers" : {
      "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/transfers"
    },
    "payment_instruments" : {
      "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/payment_instruments"
    },
    "disputes" : {
      "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/disputes"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    }
  }
}

Now that we have successfully provisioned a Merchant we’ll need to create an Identity that represents your buyer. Don’t worry though you won’t need to capture the same amount of information from your buyer. So long as you don’t pass a business_type field all the fields are optional.

Typically, we suggest at least collecting the buyer’s name and email to help with accounting, reconciliation, and chargebacks.

HTTP Request

POST https://api-test.payline.io/identities

Request Arguments

Field Type Description
first_name string, optional First name
last_name string, optional Last name
email string, optional Email
phone string, optional Phone number
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)
personal_address object, optional Customers shipping address or billing address (Full description of child attributes below)

Address-object Request Arguments

Field Type Description
line1 string, required First line of the address (max 60 characters)
line2 string, optional Second line of the address (max 60 characters)
city string, required City (max 20 characters)
region string, required 2-letter State code
postal_code string, required Zip or Postal code (max 7 characters)
country string, required 3-Letter Country code

Step 5: Tokenize a Card



curl https://api-test.payline.io/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "name": "Marshall Le", 
      "expiration_year": 2020, 
      "tags": {
          "card_name": "Business Card"
      }, 
      "number": "4957030420210454", 
      "expiration_month": 12, 
      "address": {
          "city": "San Mateo", 
          "country": "USA", 
          "region": "CA", 
          "line2": "Apartment 7", 
          "line1": "741 Douglass St", 
          "postal_code": "94114"
      }, 
      "security_code": "112", 
      "type": "PAYMENT_CARD", 
      "identity": "IDpBkS8wBTAticFPHs4gJnp2"
  }'



import io.payline.payments.processing.client.model.PaymentCard;

PaymentCard paymentCard = PaymentCard.builder()
    .name("Joe Doe")
    .identity("ID8dfS5cFQYW2Ckee7BvVR4R")
    .expirationMonth(12)
    .expirationYear(2030)
    .number("4111 1111 1111 1111")
    .securityCode("231")
    .build();
paymentCard = client.paymentCardsClient().save(paymentCard);

<?php
use Payline\Resources\PaymentCard;
use Payline\Resources\Identity;

$identity = Identity::retrieve('ID8dfS5cFQYW2Ckee7BvVR4R');
$card = new PaymentCard(
  array(
      "name"=> "Marshall Le", 
      "expiration_year"=> 2020, 
      "tags"=> array(
          "card_name"=> "Business Card"
      ), 
      "number"=> "4957030420210454", 
      "expiration_month"=> 12, 
      "address"=> array(
          "city"=> "San Mateo", 
          "country"=> "USA", 
          "region"=> "CA", 
          "line2"=> "Apartment 7", 
          "line1"=> "741 Douglass St", 
          "postal_code"=> "94114"
      ), 
      "security_code"=> "112", 
      "type"=> "PAYMENT_CARD", 
      "identity"=> "IDpBkS8wBTAticFPHs4gJnp2"
  ));
$card = $identity->createPaymentCard($card);



from payline.resources import PaymentCard

card = PaymentCard(**
  {
      "name": "Marshall Le", 
      "expiration_year": 2020, 
      "tags": {
          "card_name": "Business Card"
      }, 
      "number": "4957030420210454", 
      "expiration_month": 12, 
      "address": {
          "city": "San Mateo", 
          "country": "USA", 
          "region": "CA", 
          "line2": "Apartment 7", 
          "line1": "741 Douglass St", 
          "postal_code": "94114"
      }, 
      "security_code": "112", 
      "type": "PAYMENT_CARD", 
      "identity": "IDpBkS8wBTAticFPHs4gJnp2"
  }).save()
card = Payline::PaymentCard.new(
  {
      "name"=> "Marshall Le", 
      "expiration_year"=> 2020, 
      "tags"=> {
          "card_name"=> "Business Card"
      }, 
      "number"=> "4957030420210454", 
      "expiration_month"=> 12, 
      "address"=> {
          "city"=> "San Mateo", 
          "country"=> "USA", 
          "region"=> "CA", 
          "line2"=> "Apartment 7", 
          "line1"=> "741 Douglass St", 
          "postal_code"=> "94114"
      }, 
      "security_code"=> "112", 
      "type"=> "PAYMENT_CARD", 
      "identity"=> "IDpBkS8wBTAticFPHs4gJnp2"
  }).save

Example Response:

{
  "id" : "PIgM6zjoU4nN7PZmGwGMMaf6",
  "fingerprint" : "FPR-410674752",
  "tags" : {
    "card_name" : "Business Card"
  },
  "expiration_month" : 12,
  "expiration_year" : 2020,
  "last_four" : "0454",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : "Marshall Le",
  "address" : {
    "line1" : "741 Douglass St",
    "line2" : "Apartment 7",
    "city" : "San Mateo",
    "region" : "CA",
    "postal_code" : "94114",
    "country" : "USA"
  },
  "address_verification" : "UNKNOWN",
  "security_code_verification" : "UNKNOWN",
  "created_at" : "2017-04-24T20:22:48.65Z",
  "updated_at" : "2017-04-24T20:22:48.65Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDpBkS8wBTAticFPHs4gJnp2",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6"
    },
    "authorizations" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6/authorizations"
    },
    "identity" : {
      "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2"
    },
    "transfers" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6/transfers"
    },
    "verifications" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6/verifications"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "updates" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6/updates"
    }
  }
}

Now that we have an Identity resource representing our buyer, we’ll need to create a Payment Instrument which represents the credit card you’ll be debiting (i.e. charging).

You’ll also need to interpolate your own buyer’s Identity ID from the previous request to properly associate it.

Please review our guide on how to tokenize cards via the embedded tokenization form

HTTP Request

POST https://api-test.payline.io/payment_instruments

Request Arguments

Field Type Description
identity string, required ID of the Identity that the card should be associated
type string, required Type of Payment Instrument (for cards input PAYMENT_CARD)
number string, required Credit card account number
security_code string, optional The 3-4 digit security code for the card (i.e. CVV code)
expiration_month integer, required Expiration month (e.g. 12 for December)
expiration_year integer, required 4-digit expiration year
name string, optional Full name of the registered card holder
address object, optional Billing address (Full description of child attributes below)

Address-object Request Arguments

Field Type Description
line1 string, required First line of the address (max 60 characters)
line2 string, optional Second line of the address (max 60 characters)
city string, required City (max 20 characters)
region string, required 2-letter State code
postal_code string, required Zip or Postal code (max 7 characters)
country string, required 3-Letter Country code

Step 6: Create an Authorization

curl https://api-test.payline.io/authorizations \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "merchant_identity": "ID8dfS5cFQYW2Ckee7BvVR4R", 
      "currency": "USD", 
      "amount": 100, 
      "source": "PIgM6zjoU4nN7PZmGwGMMaf6", 
      "tags": {
          "order_number": "21DFASJSAKAS"
      }
  }'

import io.payline.payments.processing.client.model.Authorization;

Authorization authorization = client.authorizationsClient().save(
  Authorization.builder()
    .amount(100L)
    .merchantIdentity("ID8dfS5cFQYW2Ckee7BvVR4R")
    .source("PIgM6zjoU4nN7PZmGwGMMaf6")
    .build()
);

<?php
use Payline\Resources\Authorization;

$authorization = new Authorization(
  array(
      "merchant_identity"=> "ID8dfS5cFQYW2Ckee7BvVR4R", 
      "currency"=> "USD", 
      "amount"=> 100, 
      "source"=> "PIgM6zjoU4nN7PZmGwGMMaf6", 
      "tags"=> array(
          "order_number"=> "21DFASJSAKAS"
      )
  ));
$authorization = $authorization->save();



from payline.resources import Authorization
authorization = Authorization(**
  {
      "merchant_identity": "ID8dfS5cFQYW2Ckee7BvVR4R", 
      "currency": "USD", 
      "amount": 100, 
      "source": "PIgM6zjoU4nN7PZmGwGMMaf6", 
      "tags": {
          "order_number": "21DFASJSAKAS"
      }
  }).save()

authorization = Payline::Authorization.new(
  {
      "merchant_identity"=> "ID8dfS5cFQYW2Ckee7BvVR4R", 
      "currency"=> "USD", 
      "amount"=> 100, 
      "source"=> "PIgM6zjoU4nN7PZmGwGMMaf6", 
      "tags"=> {
          "order_number"=> "21DFASJSAKAS"
      }
  }).save

Example Response:

{
  "id" : "AUmaMigaS4cgphm18C3cSyvp",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : null,
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2017-04-24T20:22:53.38Z",
  "updated_at" : "2017-04-24T20:22:53.42Z",
  "trace_id" : "d37622b3-f96d-402a-b53f-f54b6894c3c9",
  "source" : "PIgM6zjoU4nN7PZmGwGMMaf6",
  "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "is_void" : false,
  "expires_at" : "2017-05-01T20:22:53.38Z",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/authorizations/AUmaMigaS4cgphm18C3cSyvp"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "merchant_identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    }
  }
}

At this point we’ve created resources representing the merchant, the buyer, and the buyer’s card.

Next you’ll need to create an Authorization. What’s a Authorization? Glad you asked! An Authorization (also known as a card hold) reserves a specific amount on a card to be captured (i.e. debited) at a later point, usually within 7 days. When an Authorization is captured it produces a Transfer resource.

To create an Authorization we’ll supply the buyer’s Payment Instrument ID as the source field and the seller’s Identity ID in the merchant_identity field. Note that the amount field is in cents.

Simple enough, right? You’ll also want to store the ID from that Authorization for your records so that we can capture those funds in the next step.

Authorizations have two possible states SUCCEEDED and FAILED. If the Authorization has succeeded, it must be captured before the expires_at or the funds will be released.

HTTP Request

POST https://api-test.payline.io/authorizations

Request Arguments

Field Type Description
source string, required The buyer’s Payment Instrument ID that you will be performing the authorization
merchant_identity string, required The ID of the Identity for the merchant that you are transacting on behalf of
amount integer, required The amount of the authorization in cents
currency string, required 3-letter ISO code designating the currency (e.g. USD)
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)

Step 7: Capture the Authorization

curl https://api-test.payline.io/authorizations/AUmaMigaS4cgphm18C3cSyvp \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -X PUT \
    -d '
  {
      "fee": "10", 
      "capture_amount": 100
  }'
import io.payline.payments.processing.client.model.Authorization;

Authorization authorization = client.authorizationsClient().fetch("AUmaMigaS4cgphm18C3cSyvp");
authorization = authorization.capture(50L);

<?php
use Payline\Resources\Authorization;

$authorization = Authorization::retrieve('AUmaMigaS4cgphm18C3cSyvp');
$authorization = $authorization->capture(50, 10);



from payline.resources import Authorization

authorization = Authorization.get(id="AUmaMigaS4cgphm18C3cSyvp")
authorization.capture(**
  {
      "fee": "10", 
      "capture_amount": 100
  })

authorization = Payline::Authorization.retrieve(:id=>"AUmaMigaS4cgphm18C3cSyvp")
authorization = authorization.capture(
  {
      "fee"=> "10", 
      "capture_amount"=> 100
  })



Example Response:

{
  "id" : "AUmaMigaS4cgphm18C3cSyvp",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : "TRbTkUqNB9bfmbBgL9KRFWux",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2017-04-24T20:22:53.33Z",
  "updated_at" : "2017-04-24T20:22:53.93Z",
  "trace_id" : "d37622b3-f96d-402a-b53f-f54b6894c3c9",
  "source" : "PIgM6zjoU4nN7PZmGwGMMaf6",
  "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "is_void" : false,
  "expires_at" : "2017-05-01T20:22:53.33Z",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/authorizations/AUmaMigaS4cgphm18C3cSyvp"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "transfer" : {
      "href" : "https://api-test.payline.io:443/transfers/TRbTkUqNB9bfmbBgL9KRFWux"
    },
    "merchant_identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    }
  }
}

Now that we have the funds held on a card, we’ll need to capture them. Failing to do so will result in the funds being released (i.e. returned) to the buyer.

Note you can capture any amount less than or equal to the amount of the original Authorization. You will also want to pass a fee. The fee field is the amount in cents you would like to keep before settling out to the merchant. For example, if you’re charging the buyer $100 on behalf of your merchant, and you’re taking a 10% service fee you’ll want to pass 1000 as the fee. This way when the funds are eventually settled out only $90 will be disbursed to your merchant.

Once successfully captured the transfer field of the Authorization will contain the ID for the corresponding Transfer resource. By default, Transfers will be in a PENDING state. PENDING means that the system hasn’t submitted the capture request as they are submitted via batch request. Once submited the state of the Transfer will update to SUCCEEDED.

Next we’re going to show you how to settle out the funds to your merchant.

HTTP Request

PUT https://api-test.payline.io/authorizations/:AUTHORIZATION_ID

URL Parameters

Parameter Description
:AUTHORIZATION_ID ID of the Authorization

Request Arguments

Field Type Description
capture_amount integer, required The amount of the Authorization you would like to capture in cents. Must be less than or equal to the amount of the Authorization
fee integer, optional Amount of the captured Authorization you would like to collect as your fee. Must be less than or equal to the amount

Step 8: Create a Batch Settlement

curl https://api-test.payline.io/identities/ID8dfS5cFQYW2Ckee7BvVR4R/settlements \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "currency": "USD", 
      "tags": {
          "Internal Daily Settlement ID": "21DFASJSAKAS"
      }
  }'

import io.payline.payments.processing.client.model.Settlement;

Settlement settlement = identity.createSettlement(
  Settlement.builder()
    .currency("USD")
    .build()
);

<?php
use Payline\Resources\Identity;
use Payline\Resources\Settlement;

$identity = Identity::retrieve('ID8dfS5cFQYW2Ckee7BvVR4R');
$settlement = new Settlement(
  array(
      "currency"=> "USD", 
      "tags"=> array(
          "Internal Daily Settlement ID"=> "21DFASJSAKAS"
      )
  ));
$settlement = $identity->createSettlement($settlement);



from payline.resources import Identity
from payline.resources import Settlement

identity = Identity.get(id="ID8dfS5cFQYW2Ckee7BvVR4R")
settlement = Settlement(**
  {
      "currency": "USD", 
      "tags": {
          "Internal Daily Settlement ID": "21DFASJSAKAS"
      }
  })
identity.create_settlement(settlement)
identity = Payline::Identity.retrieve(:id=>"ID8dfS5cFQYW2Ckee7BvVR4R")
settlement = identity.create_settlement(
  {
      "currency"=> "USD", 
      "tags"=> {
          "Internal Daily Settlement ID"=> "21DFASJSAKAS"
      }
  })

Example Response:

{
  "id" : "ST7ix1LibzhA7JvHQ7UMZgK5",
  "tags" : {
    "Internal Daily Settlement ID" : "21DFASJSAKAS"
  },
  "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "currency" : "USD",
  "created_at" : "2017-04-24T20:23:43.17Z",
  "updated_at" : "2017-04-24T20:23:43.18Z",
  "processor" : "DUMMY_V1",
  "total_amount" : 858236,
  "total_fees" : 85825,
  "total_fee" : 85825,
  "net_amount" : 772411,
  "destination" : null,
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "funding_transfers" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/funding_transfers"
    },
    "transfers" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers"
    },
    "fees" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers?type=fee"
    },
    "reversals" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers?type=reverse"
    },
    "credits" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers?type=credit"
    },
    "debits" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers?type=debit"
    }
  }
}

Awesome! Now you know how to charge a card. Next you need to settle out the funds to your merchant’s bank account (i.e. issue an ACH Credit). To do so you will create a Settlement resource. A Settlement is a logical construct representing a collection (i.e. batch) of Transfers that are intended to be paid out to a specific Merchant.

Each settlement is comprised of all the Transfers that have a SUCCEEDED state and that have not yet been previously settled out. In other words, if a merchant has a Transfer in the PENDING state it will not be included in the batch settlement. In addition, Settlements will include any refunded Transfers as a deduction. The total_amount is the net settled amount in cents (i.e. the amount in cents that will be deposited into your merchant’s bank account after your fees have been deducted).

Note that for reconciliation purposes each Settlement contains a transfers link which returns a list of all the Transfers that comprise the batch.

HTTP Request

POST https://api-test.payline.io/identities/:IDENTITY_ID/settlements

Request Arguments

Field Type Description
currency integer, required 3-letter currency code that the funds should be deposited (e.g. USD)
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)

Embedded Tokenization

Our embedded tokenization form ensures you remain out of PCI scope, while providing your end-users with a sleek, and seamless checkout experience.

With our form, sensitive card data never touches your servers and keeps you out of PCI scope by sending this info over SSL directly to Payline. For your convenience we’ve provided a jsfiddle as a live example.

Step 1: Create a Button

<!DOCTYPE html>
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <body>
        <button id="show-form">Add Your Card</button>
    </body>
</html>

Before collecting the sensitive payment information, we will need to add a button to the HTML where we’ll be hosting the iframe so that end-users can input their details.

We have provided a simple example to the right.

Step 2: Include library

To use the iframe you will need to include the library on the webpage where you’re hosting the aforementioned button. Please include the script as demonstrated to the right. Please refrain from hosting the iframe library locally as doing so prevents important updates.

<script type="text/javascript" src="https://vgs-assets.s3.amazonaws.com/payline-1.latest.js"></script>

Step 3: Configure the client

<script type="text/javascript">
    document.addEventListener("DOMContentLoaded", function(event) {
      document.getElementById('show-form').addEventListener('click', function() {
        Payline.openTokenizeCardForm({
          applicationName: 'Business Name',
          applicationId: 'APoo7cFGmGBiDzRarUMDyAwB',
        }, function (tokenizedResponse) {
          // Define a callback to send your token to your back-end server
        });
      });
    });
 </script>

Next we need to configure the client so that it associates the card with your Application. We will also need to register a click event that fires when our users click on the button, thereby rendering the iframe on the page. Then when the form is submitted you’ll be returned a unique Token resource representing the submitted card details. We will also need to define a callback for handling that response.

In the next step we’ll show you how to claim the instrument via an authenticated HTTPS request on your back-end for future use.

Example Response:

{
  "id" : "TKianXsx7RnMPpVZ8JMEE4D6",
  "fingerprint" : "FPR1145082950",
  "created_at" : "2017-04-24T20:22:55.05Z",
  "updated_at" : "2017-04-24T20:22:55.05Z",
  "instrument_type" : "PAYMENT_CARD",
  "expires_at" : "2017-04-25T20:22:55.04Z",
  "currency" : "USD",
  "_links" : {
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    }
  }
}

Step 4: Associate the Token

curl https://api-test.payline.io/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "token": "TKianXsx7RnMPpVZ8JMEE4D6", 
      "type": "TOKEN", 
      "identity": "ID8dfS5cFQYW2Ckee7BvVR4R"
  }'


import io.payline.payments.processing.client.model.PaymentCard;
import io.payline.payments.processing.client.model.PaymentCardToken;

PaymentCard card = client.paymentCardsClient().associateToken(
    PaymentCardToken.builder()
            .token("TKianXsx7RnMPpVZ8JMEE4D6")
            .identity("ID8dfS5cFQYW2Ckee7BvVR4R")
    .build()
);

<?php
use Payline\Resources\PaymentInstrument;

$card = new PaymentInstrument(
  array(
      "token"=> "TKianXsx7RnMPpVZ8JMEE4D6", 
      "type"=> "TOKEN", 
      "identity"=> "ID8dfS5cFQYW2Ckee7BvVR4R"
  ));
$card = $card->save();



from payline.resources import PaymentInstrument

payment_instrument = PaymentInstrument(**
  {
      "token": "TKianXsx7RnMPpVZ8JMEE4D6", 
      "type": "TOKEN", 
      "identity": "ID8dfS5cFQYW2Ckee7BvVR4R"
  }).save()

card = Payline::PaymentInstrument.new(
  {
      "token"=> "TKianXsx7RnMPpVZ8JMEE4D6", 
      "type"=> "TOKEN", 
      "identity"=> "ID8dfS5cFQYW2Ckee7BvVR4R"
  }).save

Example Response:

{
  "id" : "PIianXsx7RnMPpVZ8JMEE4D6",
  "fingerprint" : "FPR1145082950",
  "tags" : { },
  "expiration_month" : 12,
  "expiration_year" : 2020,
  "last_four" : "4242",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : null,
  "address" : {
    "line1" : "741 Douglass St",
    "line2" : "Apartment 7",
    "city" : "San Mateo",
    "region" : "CA",
    "postal_code" : "94114",
    "country" : "USA"
  },
  "address_verification" : "UNKNOWN",
  "security_code_verification" : "UNKNOWN",
  "created_at" : "2017-04-24T20:22:55.51Z",
  "updated_at" : "2017-04-24T20:22:55.51Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6"
    },
    "authorizations" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6/authorizations"
    },
    "identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "transfers" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6/transfers"
    },
    "verifications" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6/verifications"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "updates" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6/updates"
    }
  }
}

Associate the newly tokenized card or bank with the instrument owner’s Identity.

HTTP Request

POST https://api-test.payline.io/payment_instruments

Request Arguments

Field Type Description
token string, required ID for the Token that was returned via the tokenization client or hosted iframe
type string, required Must pass TOKEN as the value
identity string, required ID for the Identity resource which the account is to be associated

Tokenization with Hosted Fields

Library summary

The SecureForm library is a javascript library that allows you to integrate secure fields with non-secure fields in your page. The secure fields behave like traditional input fields while preventing access to the unsecured data.

Once the fields are initialized the library communicates the state of the fields through a JavaScript callback. The state object includes information about the validity, focused value and if the user has entered information in the field.

For a complete example of how to use the library please refer to this jsFiddle example.

Step 1: Include library

 <script type="text/javascript" src="https://js.verygoodvault.com/js-vgfield-2/payline.js"></script>

First we’ll need to include the library on the webpage where you’re hosting your form. Please include the script as demonstrated to the right.

Step 2: Initialize the secure form

SecureForm.create(environment, onUpdateCallback)-> Form


/*
SecureForm.create(environment, onUpdateCallback)-> Form
*/

const secureForm = SecureForm.create('sandbox', function(state) {
   // Logic for interacting with form's potential states
 });

The next step is to configure the library. This method is the single entry point into the library. It initializes and returns a Form object representing the secured form.

Arguments

Field Type Description
environment string, required sandbox for testing and live for production
onUpdateCallback function, required Callback that will be called whenever the form state changes. It receives the state object representing the current state.

Step 3: Configure the form fields

Form#field(selector, properties)-> Field


/*
Form#field(selector, properties)-> Field
*/

secureForm.field('#my-cool-parent', {
    'successColor': '#3c763d',
    'errorColor': '#a94442',
    'lineHeight': '1.5rem',
    'fontSize': '24px',
    'fontFamily': 'Comic Sans',
    'color': '#31708f',
    'placeholder': 'Card number',
    'name': 'cc-number',
    'type': 'card-number',
    'validations': [],
});

Now that we have a Form object we’ll want to style it and add any validations.

Arguments

Field Type Description
selector string, required CSS Selector that points to the element where the field will be added

Properties Object

Field Type Description
name string, required Name of the input field. Will be used when submitting the data.
type string, required Type of the input field (card-number, card-security-code, card-expiration-date, text, password, number, zip-code)
validations array, optional Array of validations that will be used to calculate the isValid state (required, validCardExpirationDate, validCardNumber, validCardSecurityCode)
placeholder string, optional Text displayed when the field is empty
successColor string, optional Text color when the field is valid
errorColor string, optional Text color when the field is invalid
color string, optional Text color
lineHeight string, optional Line height value
fontSize string, optional Size of text
fontFamily string, optional Font family used in the text.

Example Response:

{
  "number": {
    "isDirty": false,
    "isFocused": false,
    "errorMessages": [
      "is required",
      "is not a valid card number"
    ],
    "isValid": false,
    "name": "number"
  },
  "security_code": {
    "isDirty": false,
    "isFocused": false,
    "errorMessages": [
      "is required",
      "is not a valid security code"
    ],
    "isValid": false,
    "name": "security_code"
  },
  "expiration_month": {
    "isDirty": false,
    "isFocused": false,
    "errorMessages": [
      "is required"
    ],
    "isValid": false,
    "name": "expiration_month"
  },
  "expiration_year": {
    "isDirty": false,
    "isFocused": false,
    "errorMessages": [
      "is required"
    ],
    "isValid": false,
    "name": "expiration_year"
  }
}

Step 4: Submit payload and handle response

Form#submit(path, options, callback) -> Form


/*
Form#submit(path, options, callback)-> Form
*/

document.getElementById('cc-form')
  .addEventListener('submit', function(e) {
    e.preventDefault();
    secureForm.submit('/applications/APoo7cFGmGBiDzRarUMDyAwB/tokens', {
        data: {
            type: 'PAYMENT_CARD',
        },
    }, function(status, response) {
        // callback for handling response and sending token to back-end server
        console.log("Response has been received", status, response);
    });
}, false);

Example Response:

{
  "id" : "TKianXsx7RnMPpVZ8JMEE4D6",
  "fingerprint" : "FPR1145082950",
  "created_at" : "2017-04-24T20:22:55.05Z",
  "updated_at" : "2017-04-24T20:22:55.05Z",
  "instrument_type" : "PAYMENT_CARD",
  "expires_at" : "2017-04-25T20:22:55.04Z",
  "currency" : "USD",
  "_links" : {
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    }
  }
}

Finally we will need to register a click event that fires when our users submit the form and define a callback for handling the response.

Next, configure the library to your specific Application where all of the form fields will be submitted during the executed POST request. We’ll also want to register a click event that fires when our users submit the form and define a callback for handling the response.

Once you’ve handled the response you will want to store that ID to utilize the token in the future. To do this you will need to send the ID from your front-end client to your back-end server.

Arguments

Field Type Description
path string, required Path to your Application's tokens endpoint
options object, required Options object that can include additional data, such as the type of Payment Instrument
callback function, required Callback that will be executed when the HTTPRequest is finished. The callback receives the HTTP status code and the data as two arguments.

Step 5: Associate to an Identity

curl https://api-test.payline.io/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "token": "TKianXsx7RnMPpVZ8JMEE4D6", 
      "type": "TOKEN", 
      "identity": "ID8dfS5cFQYW2Ckee7BvVR4R"
  }'

import io.payline.payments.processing.client.model.PaymentCard;
import io.payline.payments.processing.client.model.PaymentCardToken;

PaymentCard card = client.paymentCardsClient().associateToken(
    PaymentCardToken.builder()
            .token("TKianXsx7RnMPpVZ8JMEE4D6")
            .identity("ID8dfS5cFQYW2Ckee7BvVR4R")
    .build()
);
<?php
use Payline\Resources\PaymentInstrument;

$card = new PaymentInstrument(
  array(
      "token"=> "TKianXsx7RnMPpVZ8JMEE4D6", 
      "type"=> "TOKEN", 
      "identity"=> "ID8dfS5cFQYW2Ckee7BvVR4R"
  ));
$card = $card->save();



from payline.resources import PaymentInstrument

payment_instrument = PaymentInstrument(**
  {
      "token": "TKianXsx7RnMPpVZ8JMEE4D6", 
      "type": "TOKEN", 
      "identity": "ID8dfS5cFQYW2Ckee7BvVR4R"
  }).save()

card = Payline::PaymentInstrument.new(
  {
      "token"=> "TKianXsx7RnMPpVZ8JMEE4D6", 
      "type"=> "TOKEN", 
      "identity"=> "ID8dfS5cFQYW2Ckee7BvVR4R"
  }).save

Example Response:

{
  "id" : "PIianXsx7RnMPpVZ8JMEE4D6",
  "fingerprint" : "FPR1145082950",
  "tags" : { },
  "expiration_month" : 12,
  "expiration_year" : 2020,
  "last_four" : "4242",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : null,
  "address" : {
    "line1" : "741 Douglass St",
    "line2" : "Apartment 7",
    "city" : "San Mateo",
    "region" : "CA",
    "postal_code" : "94114",
    "country" : "USA"
  },
  "address_verification" : "UNKNOWN",
  "security_code_verification" : "UNKNOWN",
  "created_at" : "2017-04-24T20:22:55.51Z",
  "updated_at" : "2017-04-24T20:22:55.51Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6"
    },
    "authorizations" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6/authorizations"
    },
    "identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "transfers" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6/transfers"
    },
    "verifications" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6/verifications"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "updates" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6/updates"
    }
  }
}

Before you can use the newly tokenized card or bank account you will need to associate it with an Identity. To do this you must make an authenticated POST request to the /payment_instruments endpoint with the relevant token and Identity information.

HTTP Request

POST https://api-test.payline.io/payment_instruments

Request Arguments

Field Type Description
token string, required ID for the Token that was returned via the tokenization client
type string, required Must pass TOKEN as the value
identity string, required ID for the Identity resource which the account is to be associated

Testing for specific responses and errors

Before taking your integration to production, use the information below to test it thoroughly.

Amount Description
100 Success amount
102 Failed amount
103 Canceled amount
104 Exception amount
888888 Disputed amount
193 Insufficient funds amount
194 Invalid card number amount
889986 AVS total failure amount
889987 CVC failure amount
889988 Risk amount canceled amount
Card Description
4000000000000036 Payment card AVS total failure
4000000000000127 Payment card CVC failure

Authorizations

An Authorization (also known as a card hold) reserves a specific amount on a card to be captured (i.e. debited) at a later date, usually within 7 days. When an Authorization is captured it produces a Transfer resource.

Create an Authorization

curl https://api-test.payline.io/authorizations \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "merchant_identity": "ID8dfS5cFQYW2Ckee7BvVR4R", 
      "currency": "USD", 
      "amount": 100, 
      "source": "PIgM6zjoU4nN7PZmGwGMMaf6", 
      "tags": {
          "order_number": "21DFASJSAKAS"
      }
  }'

import io.payline.payments.processing.client.model.Authorization;

Authorization authorization = client.authorizationsClient().save(
  Authorization.builder()
    .amount(100L)
    .merchantIdentity("ID8dfS5cFQYW2Ckee7BvVR4R")
    .source("PIgM6zjoU4nN7PZmGwGMMaf6")
    .build()
);


<?php
use Payline\Resources\Authorization;

$authorization = new Authorization(
  array(
      "merchant_identity"=> "ID8dfS5cFQYW2Ckee7BvVR4R", 
      "currency"=> "USD", 
      "amount"=> 100, 
      "source"=> "PIgM6zjoU4nN7PZmGwGMMaf6", 
      "tags"=> array(
          "order_number"=> "21DFASJSAKAS"
      )
  ));
$authorization = $authorization->save();




from payline.resources import Authorization

authorization = Authorization(**
  {
      "merchant_identity": "ID8dfS5cFQYW2Ckee7BvVR4R", 
      "currency": "USD", 
      "amount": 100, 
      "source": "PIgM6zjoU4nN7PZmGwGMMaf6", 
      "tags": {
          "order_number": "21DFASJSAKAS"
      }
  }).save()
authorization = Payline::Authorization.new(
  {
      "merchant_identity"=> "ID8dfS5cFQYW2Ckee7BvVR4R", 
      "currency"=> "USD", 
      "amount"=> 100, 
      "source"=> "PIgM6zjoU4nN7PZmGwGMMaf6", 
      "tags"=> {
          "order_number"=> "21DFASJSAKAS"
      }
  }).save

Example Response:

{
  "id" : "AUmaMigaS4cgphm18C3cSyvp",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : null,
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2017-04-24T20:22:53.38Z",
  "updated_at" : "2017-04-24T20:22:53.42Z",
  "trace_id" : "d37622b3-f96d-402a-b53f-f54b6894c3c9",
  "source" : "PIgM6zjoU4nN7PZmGwGMMaf6",
  "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "is_void" : false,
  "expires_at" : "2017-05-01T20:22:53.38Z",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/authorizations/AUmaMigaS4cgphm18C3cSyvp"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "merchant_identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    }
  }
}

Authorizations have two possible states SUCCEEDED and FAILED. If the Authorization has succeeded, it must be captured before the expires_at or the funds will be released.

HTTP Request

POST https://api-test.payline.io/authorizations

Request Arguments

Field Type Description
source string, required The Payment Instrument that you will be performing the authorization
merchant_identity string, required The ID of the Identity for the merchant that you are transacting on behalf of
amount integer, required The amount of the authorization in cents
currency string, required 3-letter ISO code designating the currency (e.g. USD)
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)

Capture an Authorization

curl https://api-test.payline.io/authorizations/AUmaMigaS4cgphm18C3cSyvp \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -X PUT \
    -d '
  {
      "fee": "10", 
      "capture_amount": 100
  }'


import io.payline.payments.processing.client.model.Authorization;

Authorization authorization = client.authorizationsClient().fetch("AUmaMigaS4cgphm18C3cSyvp");
Long captureAmount = 50L;
Long feeAmount = 10L;
authorization = authorization.capture(captureAmount, feeAmount);

<?php
use Payline\Resources\Authorization;

$authorization = Authorization::retrieve('AUmaMigaS4cgphm18C3cSyvp');
$authorization = $authorization->capture(50, 10);



from payline.resources import Authorization

authorization = Authorization.get(id="AUmaMigaS4cgphm18C3cSyvp")
authorization.capture(**
  {
      "fee": "10", 
      "capture_amount": 100
  })

authorization = Payline::Authorization.retrieve(:id=>"AUmaMigaS4cgphm18C3cSyvp")
authorization = authorization.capture(
  {
      "fee"=> "10", 
      "capture_amount"=> 100
  })



Example Response:

{
  "id" : "AUmaMigaS4cgphm18C3cSyvp",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : "TRbTkUqNB9bfmbBgL9KRFWux",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2017-04-24T20:22:53.33Z",
  "updated_at" : "2017-04-24T20:22:53.93Z",
  "trace_id" : "d37622b3-f96d-402a-b53f-f54b6894c3c9",
  "source" : "PIgM6zjoU4nN7PZmGwGMMaf6",
  "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "is_void" : false,
  "expires_at" : "2017-05-01T20:22:53.33Z",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/authorizations/AUmaMigaS4cgphm18C3cSyvp"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "transfer" : {
      "href" : "https://api-test.payline.io:443/transfers/TRbTkUqNB9bfmbBgL9KRFWux"
    },
    "merchant_identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    }
  }
}

Once successfully captured the transfer field of the Authorization will contain the ID for the corresponding Transfer resource. By default, Transfers will be in a PENDING state. PENDING means that the system hasn’t submitted the capture request as they are submitted via batch request. Once submited the state of the Transfer will update to SUCCEEDED.

HTTP Request

PUT https://api-test.payline.io/authorizations/:AUTHORIZATION_ID

URL Parameters

Parameter Description
:AUTHORIZATION_ID ID of the Authorization

Request Arguments

Field Type Description
capture_amount integer, required The amount of the Authorization you would like to capture in cents. Must be less than or equal to the amount of the Authorization
fee integer, optional Amount of the captured Authorization you would like to collect as your fee. Must be less than or equal to the amount

Void an Authorization


curl https://api-test.payline.io/authorizations/AUgcS7bZfcdjoo8bnMHkhzXo \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -X PUT \
    -d '
  {
      "void_me": true
  }'

Authorization authorization = client.authorizationsClient().fetch(authorization.getId());
authorization.voidMe(true);

<?php
use Payline\Resources\Authorization;

$authorization = Authorization::retrieve('AUmaMigaS4cgphm18C3cSyvp');
$authorization->void(true);
$authorization = $authorization->save();




from payline.resources import Authorization

authorization = Authorization.get(id="AUmaMigaS4cgphm18C3cSyvp")
authorization.void()

authorization = Payline::Authorization.retrieve(:id=>"AUmaMigaS4cgphm18C3cSyvp")
authorization = authorization.void

Example Response:

{
  "id" : "AUgcS7bZfcdjoo8bnMHkhzXo",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : null,
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2017-04-24T20:22:56.11Z",
  "updated_at" : "2017-04-24T20:22:56.96Z",
  "trace_id" : "ef84926d-661c-411a-b531-cbe632f9f72e",
  "source" : "PIgM6zjoU4nN7PZmGwGMMaf6",
  "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "is_void" : true,
  "expires_at" : "2017-05-01T20:22:56.11Z",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/authorizations/AUgcS7bZfcdjoo8bnMHkhzXo"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "merchant_identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    }
  }
}

Cancels the Authorization thereby releasing the funds. After voiding an Authorization it can no longer be captured.

HTTP Request

PUT https://api-test.payline.io/authorizations/:AUTHORIZATION_ID

URL Parameters

Parameter Description
:AUTHORIZATION_ID ID of the Authorization

Request Arguments

Field Type Description
void_me boolean, required Set to True to void the Authorization

Retrieve an Authorization


curl https://api-test.payline.io/authorizations/AUmaMigaS4cgphm18C3cSyvp \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3


import io.payline.payments.processing.client.model.Authorization;

Authorization authorization = client.authorizationsClient().fetch("AUmaMigaS4cgphm18C3cSyvp");

<?php
use Payline\Resources\Authorization;

$authorization = Authorization::retrieve('AUmaMigaS4cgphm18C3cSyvp');



from payline.resources import Authorization

authorization = Authorization.get(id="AUmaMigaS4cgphm18C3cSyvp")
authorization = Payline::Authorization.retrieve(:id=>"AUmaMigaS4cgphm18C3cSyvp")


Example Response:

{
  "id" : "AUmaMigaS4cgphm18C3cSyvp",
  "amount" : 100,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : "TRbTkUqNB9bfmbBgL9KRFWux",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2017-04-24T20:22:53.33Z",
  "updated_at" : "2017-04-24T20:22:53.93Z",
  "trace_id" : "d37622b3-f96d-402a-b53f-f54b6894c3c9",
  "source" : "PIgM6zjoU4nN7PZmGwGMMaf6",
  "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "is_void" : false,
  "expires_at" : "2017-05-01T20:22:53.33Z",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/authorizations/AUmaMigaS4cgphm18C3cSyvp"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "transfer" : {
      "href" : "https://api-test.payline.io:443/transfers/TRbTkUqNB9bfmbBgL9KRFWux"
    },
    "merchant_identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    }
  }
}

HTTP Request

GET https://api-test.payline.io/authorizations/:AUTHORIZATION_ID

URL Parameters

Parameter Description
:AUTHORIZATION_ID ID of the Authorization

List all Authorizations

curl https://api-test.payline.io/authorizations/ \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3

import io.payline.payments.processing.client.model.Authorization;

client.authorizationsClient().<Resources<Authorization>>resourcesIterator()
  .forEachRemaining(page-> {
    Collection<Authorization> authorizations = page.getContent();
    //do something
  });
<?php
use Payline\Resources\Authorization;

$authorizations = Authorization::getPagination("/authorizations");




from payline.resources import Authorization

authorization = Authorization.get()
authorizations = Payline::Authorization.retrieve

Example Response:

{
  "_embedded" : {
    "authorizations" : [ {
      "id" : "AUgcS7bZfcdjoo8bnMHkhzXo",
      "amount" : 100,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "currency" : "USD",
      "transfer" : null,
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2017-04-24T20:22:56.11Z",
      "updated_at" : "2017-04-24T20:22:56.96Z",
      "trace_id" : "ef84926d-661c-411a-b531-cbe632f9f72e",
      "source" : "PIgM6zjoU4nN7PZmGwGMMaf6",
      "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
      "is_void" : true,
      "expires_at" : "2017-05-01T20:22:56.11Z",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/authorizations/AUgcS7bZfcdjoo8bnMHkhzXo"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "merchant_identity" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
        }
      }
    }, {
      "id" : "AUmaMigaS4cgphm18C3cSyvp",
      "amount" : 100,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "currency" : "USD",
      "transfer" : "TRbTkUqNB9bfmbBgL9KRFWux",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2017-04-24T20:22:53.33Z",
      "updated_at" : "2017-04-24T20:22:53.93Z",
      "trace_id" : "d37622b3-f96d-402a-b53f-f54b6894c3c9",
      "source" : "PIgM6zjoU4nN7PZmGwGMMaf6",
      "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
      "is_void" : false,
      "expires_at" : "2017-05-01T20:22:53.33Z",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/authorizations/AUmaMigaS4cgphm18C3cSyvp"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "transfer" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbTkUqNB9bfmbBgL9KRFWux"
        },
        "merchant_identity" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io/authorizations?offset=0&limit=20&sort=created_at,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 2
  }
}

HTTP Request

GET https://api-test.payline.io/authorizations/

Identities

An Identity resource represents either a buyer or a merchant and is in a many ways the centerpiece of the payment API’s architecture. Transfers and Payment Instruments must be associated with an Identity. For both buyers ans merchants this structure makes it easy to manage and reconcile their associated banks accounts, transaction history, and payouts.

Create an Identity for a Buyer



curl https://api-test.payline.io/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "tags": {
          "key": "value"
      }, 
      "entity": {
          "phone": "7145677613", 
          "first_name": "Alex", 
          "last_name": "Serna", 
          "email": "therock@gmail.com", 
          "personal_address": {
              "city": "San Mateo", 
              "country": "USA", 
              "region": "CA", 
              "line2": "Apartment 7", 
              "line1": "741 Douglass St", 
              "postal_code": "94114"
          }
      }
  }'


import io.payline.payments.processing.client.model.Identity;

Identity identity = client.identitiesClient().save(
  Identity.builder()
    .entity(
      Entity.builder()
        .firstName("dwayne")
        .lastName("Sunkhronos")
        .email("user@example.org")
        .build()
    )
    .build()
);

<?php
use Payline\Resources\Identity;

$identity = new Identity(
  array(
      "tags"=> array(
          "key"=> "value"
      ), 
      "entity"=> array(
          "phone"=> "7145677613", 
          "first_name"=> "Alex", 
          "last_name"=> "Serna", 
          "email"=> "therock@gmail.com", 
          "personal_address"=> array(
              "city"=> "San Mateo", 
              "country"=> "USA", 
              "region"=> "CA", 
              "line2"=> "Apartment 7", 
              "line1"=> "741 Douglass St", 
              "postal_code"=> "94114"
          )
      )
  ));
$identity = $identity->save();



from payline.resources import Identity

identity = Identity(**
  {
      "tags": {
          "key": "value"
      }, 
      "entity": {
          "phone": "7145677613", 
          "first_name": "Alex", 
          "last_name": "Serna", 
          "email": "therock@gmail.com", 
          "personal_address": {
              "city": "San Mateo", 
              "country": "USA", 
              "region": "CA", 
              "line2": "Apartment 7", 
              "line1": "741 Douglass St", 
              "postal_code": "94114"
          }
      }
  }).save()
identity = Payline::Identity.new(
  {
      "tags"=> {
          "key"=> "value"
      }, 
      "entity"=> {
          "phone"=> "7145677613", 
          "first_name"=> "Alex", 
          "last_name"=> "Serna", 
          "email"=> "therock@gmail.com", 
          "personal_address"=> {
              "city"=> "San Mateo", 
              "country"=> "USA", 
              "region"=> "CA", 
              "line2"=> "Apartment 7", 
              "line1"=> "741 Douglass St", 
              "postal_code"=> "94114"
          }
      }
  }).save

Example Response:

{
  "id" : "IDpBkS8wBTAticFPHs4gJnp2",
  "entity" : {
    "title" : null,
    "first_name" : "Alex",
    "last_name" : "Serna",
    "email" : "therock@gmail.com",
    "business_name" : null,
    "business_type" : null,
    "doing_business_as" : null,
    "phone" : "7145677613",
    "business_phone" : null,
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "business_address" : null,
    "mcc" : null,
    "dob" : null,
    "max_transaction_amount" : 0,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : null,
    "annual_card_volume" : 0,
    "has_accepted_credit_cards_previously" : false,
    "incorporation_date" : null,
    "principal_percentage_ownership" : null,
    "short_business_name" : null,
    "ownership_type" : null,
    "tax_id_provided" : false,
    "business_tax_id_provided" : false,
    "default_statement_descriptor" : null
  },
  "tags" : {
    "key" : "value"
  },
  "created_at" : "2017-04-24T20:22:48.23Z",
  "updated_at" : "2017-04-24T20:22:48.23Z",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2"
    },
    "verifications" : {
      "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/verifications"
    },
    "merchants" : {
      "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/merchants"
    },
    "settlements" : {
      "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/settlements"
    },
    "authorizations" : {
      "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/authorizations"
    },
    "transfers" : {
      "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/transfers"
    },
    "payment_instruments" : {
      "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/payment_instruments"
    },
    "disputes" : {
      "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/disputes"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    }
  }
}

All fields for a buyer’s Identity are optional. However, a business_type field should not be passed. Passing a business_type indicates that the Identity should be treated as a merchant.

HTTP Request

POST https://api-test.payline.io/identities

Request Arguments

Field Type Description
first_name string, optional First name
last_name string, optional Last name
phone string, optional Phone number
email string, optional Email address
line1 string, optional First line of the address (max 60 characters)
line2 string, optional Second line of the address (max 60 characters)
city string, optional City (max 20 characters)
region string, optional 2-letter State code
postal_code string, optional Zip or Postal code (max 7 characters)
country string, optional 3-Letter Country code
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)

Create an Identity for a Merchant



curl https://api-test.payline.io/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "tags": {
          "Studio Rating": "4.7"
      }, 
      "entity": {
          "last_name": "Sunkhronos", 
          "max_transaction_amount": 12000000, 
          "has_accepted_credit_cards_previously": true, 
          "default_statement_descriptor": "Prestige World Wide", 
          "personal_address": {
              "city": "San Mateo", 
              "country": "USA", 
              "region": "CA", 
              "line2": "Apartment 7", 
              "line1": "741 Douglass St", 
              "postal_code": "94114"
          }, 
          "incorporation_date": {
              "year": 1978, 
              "day": 27, 
              "month": 6
          }, 
          "business_address": {
              "city": "San Mateo", 
              "country": "USA", 
              "region": "CA", 
              "line2": "Apartment 8", 
              "line1": "741 Douglass St", 
              "postal_code": "94114"
          }, 
          "ownership_type": "PRIVATE", 
          "first_name": "dwayne", 
          "title": "CEO", 
          "business_tax_id": "123456789", 
          "doing_business_as": "Prestige World Wide", 
          "principal_percentage_ownership": 50, 
          "email": "user@example.org", 
          "mcc": "0742", 
          "phone": "1234567890", 
          "business_name": "Prestige World Wide", 
          "tax_id": "123456789", 
          "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP", 
          "business_phone": "+1 (408) 756-4497", 
          "dob": {
              "year": 1978, 
              "day": 27, 
              "month": 6
          }, 
          "url": "www.PrestigeWorldWide.com", 
          "annual_card_volume": 12000000
      }
  }'


import io.payline.payments.processing.client.model.Address;
import io.payline.payments.processing.client.model.BankAccountType;
import io.payline.payments.processing.client.model.BusinessType;
import io.payline.payments.processing.client.model.Date;
import io.payline.payments.processing.client.model.Entity;
import io.payline.payments.processing.client.model.Identity;

Identity identity = client.identitiesClient().save(
  Identity.builder()
    .entity(
      Entity.builder()
        .title("CEO")
        .firstName("dwayne")
        .lastName("Sunkhronos")
        .email("user@example.org")
        .businessName("business inc")
        .businessType(BusinessType.LIMITED_LIABILITY_COMPANY)
        .doingBusinessAs("doingBusinessAs")
        .phone("1234567890")
        .businessPhone("+1 (408) 756-4497")
        .taxId("123456789")
        .businessTaxId("123456789")
        .personalAddress(
          Address.builder()
            .line1("741 Douglass St")
            .line2("Apartment 7")
            .city("San Mateo")
            .region("CA")
            .postalCode("94114")
            .country("USA")
            .build()
        )
        .businessAddress(
          Address.builder()
            .line1("741 Douglass St")
            .line2("Apartment 7")
            .city("San Mateo")
            .region("CA")
            .postalCode("94114")
            .country("USA")
            .build()
        )
        .dob(Date.builder()
          .day(27)
          .month(5)
          .year(1978)
          .build()
        )
        .settlementCurrency("USD")
        .settlementBankAccount(BankAccountType.CORPORATE)
        .maxTransactionAmount(1000l)
        .mcc(7399)
        .url("http://sample-entity.com")
        .annualCardVolume(100)
        .defaultStatementDescriptor("Business Inc")
        .incorporationDate(Date.builder()
          .day(1)
          .month(12)
          .year(2012)
          .build()
        )
        .principalPercentageOwnership(51)
        .ownershipType("PRIVATE")
        .hasAcceptedCreditCardsPreviously(false)
        .build()
    )
    .build()
);

<?php
use Payline\Resources\Identity;

$identity = new Identity(
  array(
      "tags"=> array(
          "Studio Rating"=> "4.7"
      ), 
      "entity"=> array(
          "last_name"=> "Sunkhronos", 
          "max_transaction_amount"=> 12000000, 
          "has_accepted_credit_cards_previously"=> true, 
          "default_statement_descriptor"=> "Prestige World Wide", 
          "personal_address"=> array(
              "city"=> "San Mateo", 
              "country"=> "USA", 
              "region"=> "CA", 
              "line2"=> "Apartment 7", 
              "line1"=> "741 Douglass St", 
              "postal_code"=> "94114"
          ), 
          "incorporation_date"=> array(
              "year"=> 1978, 
              "day"=> 27, 
              "month"=> 6
          ), 
          "business_address"=> array(
              "city"=> "San Mateo", 
              "country"=> "USA", 
              "region"=> "CA", 
              "line2"=> "Apartment 8", 
              "line1"=> "741 Douglass St", 
              "postal_code"=> "94114"
          ), 
          "ownership_type"=> "PRIVATE", 
          "first_name"=> "dwayne", 
          "title"=> "CEO", 
          "business_tax_id"=> "123456789", 
          "doing_business_as"=> "Prestige World Wide", 
          "principal_percentage_ownership"=> 50, 
          "email"=> "user@example.org", 
          "mcc"=> "0742", 
          "phone"=> "1234567890", 
          "business_name"=> "Prestige World Wide", 
          "tax_id"=> "123456789", 
          "business_type"=> "INDIVIDUAL_SOLE_PROPRIETORSHIP", 
          "business_phone"=> "+1 (408) 756-4497", 
          "dob"=> array(
              "year"=> 1978, 
              "day"=> 27, 
              "month"=> 6
          ), 
          "url"=> "www.PrestigeWorldWide.com", 
          "annual_card_volume"=> 12000000
      )
  )
);
$identity = $identity->save();



from payline.resources import Identity

identity = Identity(**
  {
      "tags": {
          "Studio Rating": "4.7"
      }, 
      "entity": {
          "last_name": "Sunkhronos", 
          "max_transaction_amount": 12000000, 
          "has_accepted_credit_cards_previously": True, 
          "default_statement_descriptor": "Prestige World Wide", 
          "personal_address": {
              "city": "San Mateo", 
              "country": "USA", 
              "region": "CA", 
              "line2": "Apartment 7", 
              "line1": "741 Douglass St", 
              "postal_code": "94114"
          }, 
          "incorporation_date": {
              "year": 1978, 
              "day": 27, 
              "month": 6
          }, 
          "business_address": {
              "city": "San Mateo", 
              "country": "USA", 
              "region": "CA", 
              "line2": "Apartment 8", 
              "line1": "741 Douglass St", 
              "postal_code": "94114"
          }, 
          "ownership_type": "PRIVATE", 
          "first_name": "dwayne", 
          "title": "CEO", 
          "business_tax_id": "123456789", 
          "doing_business_as": "Prestige World Wide", 
          "principal_percentage_ownership": 50, 
          "email": "user@example.org", 
          "mcc": "0742", 
          "phone": "1234567890", 
          "business_name": "Prestige World Wide", 
          "tax_id": "123456789", 
          "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP", 
          "business_phone": "+1 (408) 756-4497", 
          "dob": {
              "year": 1978, 
              "day": 27, 
              "month": 6
          }, 
          "url": "www.PrestigeWorldWide.com", 
          "annual_card_volume": 12000000
      }
  }).save()
identity = Payline::Identity.new(
  {
      "tags"=> {
          "Studio Rating"=> "4.7"
      }, 
      "entity"=> {
          "last_name"=> "Sunkhronos", 
          "max_transaction_amount"=> 12000000, 
          "has_accepted_credit_cards_previously"=> true, 
          "default_statement_descriptor"=> "Prestige World Wide", 
          "personal_address"=> {
              "city"=> "San Mateo", 
              "country"=> "USA", 
              "region"=> "CA", 
              "line2"=> "Apartment 7", 
              "line1"=> "741 Douglass St", 
              "postal_code"=> "94114"
          }, 
          "incorporation_date"=> {
              "year"=> 1978, 
              "day"=> 27, 
              "month"=> 6
          }, 
          "business_address"=> {
              "city"=> "San Mateo", 
              "country"=> "USA", 
              "region"=> "CA", 
              "line2"=> "Apartment 8", 
              "line1"=> "741 Douglass St", 
              "postal_code"=> "94114"
          }, 
          "ownership_type"=> "PRIVATE", 
          "first_name"=> "dwayne", 
          "title"=> "CEO", 
          "business_tax_id"=> "123456789", 
          "doing_business_as"=> "Prestige World Wide", 
          "principal_percentage_ownership"=> 50, 
          "email"=> "user@example.org", 
          "mcc"=> "0742", 
          "phone"=> "1234567890", 
          "business_name"=> "Prestige World Wide", 
          "tax_id"=> "123456789", 
          "business_type"=> "INDIVIDUAL_SOLE_PROPRIETORSHIP", 
          "business_phone"=> "+1 (408) 756-4497", 
          "dob"=> {
              "year"=> 1978, 
              "day"=> 27, 
              "month"=> 6
          }, 
          "url"=> "www.PrestigeWorldWide.com", 
          "annual_card_volume"=> 12000000
      }
  }).save

Example Response:

{
  "id" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "entity" : {
    "title" : "CEO",
    "first_name" : "dwayne",
    "last_name" : "Sunkhronos",
    "email" : "user@example.org",
    "business_name" : "Prestige World Wide",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "doing_business_as" : "Prestige World Wide",
    "phone" : "1234567890",
    "business_phone" : "+1 (408) 756-4497",
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "business_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 8",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "mcc" : "0742",
    "dob" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "max_transaction_amount" : 12000000,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : "www.PrestigeWorldWide.com",
    "annual_card_volume" : 12000000,
    "has_accepted_credit_cards_previously" : true,
    "incorporation_date" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "principal_percentage_ownership" : 50,
    "short_business_name" : null,
    "ownership_type" : "PRIVATE",
    "tax_id_provided" : true,
    "business_tax_id_provided" : true,
    "default_statement_descriptor" : "Prestige World Wide"
  },
  "tags" : {
    "Studio Rating" : "4.7"
  },
  "created_at" : "2017-04-24T20:22:41.83Z",
  "updated_at" : "2017-04-24T20:22:41.83Z",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "verifications" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/verifications"
    },
    "merchants" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/merchants"
    },
    "settlements" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/settlements"
    },
    "authorizations" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/authorizations"
    },
    "transfers" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/transfers"
    },
    "payment_instruments" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/payment_instruments"
    },
    "disputes" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/disputes"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    }
  }
}

Before we can begin charging cards we’ll need to provision a Merchant account for your seller. This requires 3-steps:

  1. Create an Identity resource with the sender’s underwriting and identity verification information (API request to the right)

  2. Create a Payment Instrument representing the sender’s bank account where processed funds will be settled (i.e. deposited)

HTTP Request

POST https://api-test.payline.io/identities

Business-specific Request Arguments

Field Type Description
business_name string, required Merchant’s full legal business name (If INDIVIDUAL_SOLE_PROPRIETORSHIP, please input first name, Full legal last name and middle initial; max 120 characters)
doing_business_as string, required Alternate name of the business. If no other name is used please use the same value for business_name (max 60 characters)
business_type string, required Please select one of the following values: INDIVIDUAL_SOLE_PROPRIETORSHIP, CORPORATION, LIMITED_LIABILITY_COMPANY, PARTNERSHIP, ASSOCIATION_ESTATE_TRUST, TAX_EXEMPT_ORGANIZATION, INTERNATIONAL_ORGANIZATION, GOVERNMENT_AGENCY
business_tax_id string, required Nine digit Tax Identification Number (TIN), Employer Identification Number (EIN) or if the business_type is INDIVIDUAL_SOLE_PROPRIETORSHIP and a Tax ID is not available, the principal’s Social Security Number (SSN)
url string, required Merchant’s publicly available website (max 100 characters)
business_phone string, required Customer service phone number where the merchant can be reached (max 10 characters)
incorporation_date object, required Date company was founded (See below for a full list of the child attributes)
business_address object, required Primary address for the legal entity (Full description of child attributes below)
ownership_type string, required Values can be either PUBLIC to indicate a publicly traded company or PRIVATE for privately held businesses

Principal-specific Request Arguments

(i.e. authorized representative or primary contact responsible for the account)

Field Type Description
first_name string, required Full legal first name of the merchant’s principal representative (max 20 characters)
last_name string, required Full legal last name of the merchant’s principal representative (max 20 characters)
title string, required Principal’s corporate title or role (i.e. Chief Executive Officer, CFO, etc.; max 60 characters)
principal_percentage_ownership integer, required Percentage of company owned by the principal (min 0; max 100)
tax_id string, required Nine digit Social Security Number (SSN) for the principal
dob object, required Principal’s date of birth (Full description of child attributes below)
phone string, required Principal’s phone number (max 10 characters)
email string, required Principal’s email address where they can be reached (max 100 characters)
personal_address object, required Principal’s personal home address. This field is used for identity verification purposes (Full description of child attributes below)

Processing-specific Request Arguments

Field Type Description
default_statement_descriptor string, required Billing descriptor displayed on the buyer’s bank or card statement (Length must be between 1 and 20 characters)
annual_card_volume integer, required Approximate annual credit card sales expected to be processed in cents by this merchant (max 23 characters)
max_transaction_amount integer, required Maximum amount that can be transacted for a single transaction in cents (max 12 characters)
mcc string, required Merchant Category Code (MCC) that this merchant will be classified under
has_accepted_credit_cards_previously boolean, optional Defaults to false if not passed

Address-object Request Arguments

Field Type Description
line1 string, required First line of the address (max 60 characters)
line2 string, optional Second line of the address (max 60 characters)
city string, required City (max 20 characters)
region string, required 2-letter State code
postal_code string, required Zip or Postal code (max 7 characters)
country string, required 3-Letter Country code

Incorporation Date-object Request Arguments

Field Type Description
day integer, required Day business was incorporated (between 1 and 31)
month integer, required Month business was incorporated (between 1 and 12)
year integer, required Year business was incorporated (4-digit)

DOB-object Request Arguments

Field Type Description
day integer, required Day of birth (between 1 and 31)
month integer, required Month of birth (between 1 and 12)
year integer, required Year of birth (4-digit)

Retrieve a Identity


curl https://api-test.payline.io/identities/ID8dfS5cFQYW2Ckee7BvVR4R \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3


import io.payline.payments.processing.client.model.Identity;

Identity identity = client.identitiesClient().fetch("ID8dfS5cFQYW2Ckee7BvVR4R");

<?php
use Payline\Resources\Identity;

$identity = Identity::retrieve('ID8dfS5cFQYW2Ckee7BvVR4R');


from payline.resources import Identity
identity = Identity.get(id="ID8dfS5cFQYW2Ckee7BvVR4R")

identity = Payline::Identity.retrieve(:id=>"ID8dfS5cFQYW2Ckee7BvVR4R")


Example Response:

{
  "id" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "entity" : {
    "title" : "CEO",
    "first_name" : "dwayne",
    "last_name" : "Sunkhronos",
    "email" : "user@example.org",
    "business_name" : "Prestige World Wide",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "doing_business_as" : "Prestige World Wide",
    "phone" : "1234567890",
    "business_phone" : "+1 (408) 756-4497",
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "business_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 8",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "mcc" : "0742",
    "dob" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "max_transaction_amount" : 12000000,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : "www.PrestigeWorldWide.com",
    "annual_card_volume" : 12000000,
    "has_accepted_credit_cards_previously" : true,
    "incorporation_date" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "principal_percentage_ownership" : 50,
    "short_business_name" : null,
    "ownership_type" : "PRIVATE",
    "tax_id_provided" : true,
    "business_tax_id_provided" : true,
    "default_statement_descriptor" : "Prestige World Wide"
  },
  "tags" : {
    "Studio Rating" : "4.7"
  },
  "created_at" : "2017-04-24T20:22:41.81Z",
  "updated_at" : "2017-04-24T20:22:41.81Z",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "verifications" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/verifications"
    },
    "merchants" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/merchants"
    },
    "settlements" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/settlements"
    },
    "authorizations" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/authorizations"
    },
    "transfers" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/transfers"
    },
    "payment_instruments" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/payment_instruments"
    },
    "disputes" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/disputes"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    }
  }
}

HTTP Request

GET https://api-test.payline.io/identities/:IDENTITY_ID

URL Parameters

Parameter Description
:IDENTITY_ID ID of the Identity

List all Identities

curl https://api-test.payline.io/identities/ \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3


import io.payline.payments.processing.client.model.Identity;

client.identitiesClient().<Resources<Identity>>resourcesIterator()
  .forEachRemaining(page -> {
    Collection<Identity> identities = page.getContent();
    //do something
  });

<?php
use Payline\Resources\Identity;

$identities= Identity::getPagination("/identities");




from payline.resources import Identity
identity = Identity.get()

identities = Payline::Identity.retrieve


Example Response:

{
  "_embedded" : {
    "identities" : [ {
      "id" : "IDpBkS8wBTAticFPHs4gJnp2",
      "entity" : {
        "title" : null,
        "first_name" : "Alex",
        "last_name" : "Serna",
        "email" : "therock@gmail.com",
        "business_name" : null,
        "business_type" : null,
        "doing_business_as" : null,
        "phone" : "7145677613",
        "business_phone" : null,
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : null,
        "mcc" : null,
        "dob" : null,
        "max_transaction_amount" : 0,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : null,
        "annual_card_volume" : 0,
        "has_accepted_credit_cards_previously" : false,
        "incorporation_date" : null,
        "principal_percentage_ownership" : null,
        "short_business_name" : null,
        "ownership_type" : null,
        "tax_id_provided" : false,
        "business_tax_id_provided" : false,
        "default_statement_descriptor" : null
      },
      "tags" : {
        "key" : "value"
      },
      "created_at" : "2017-04-24T20:22:48.22Z",
      "updated_at" : "2017-04-24T20:22:48.22Z",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/verifications"
        },
        "merchants" : {
          "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/merchants"
        },
        "settlements" : {
          "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/settlements"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/authorizations"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/transfers"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/payment_instruments"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2/disputes"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    }, {
      "id" : "IDoicMTU2deqxnNLJF8hC4Gc",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Dunder Mifflin",
        "business_type" : "GOVERNMENT_AGENCY",
        "doing_business_as" : "Dunder Mifflin",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.DunderMifflin.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PUBLIC",
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Dunder Mifflin"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2017-04-24T20:22:45.44Z",
      "updated_at" : "2017-04-24T20:22:45.44Z",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/identities/IDoicMTU2deqxnNLJF8hC4Gc"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/identities/IDoicMTU2deqxnNLJF8hC4Gc/verifications"
        },
        "merchants" : {
          "href" : "https://api-test.payline.io:443/identities/IDoicMTU2deqxnNLJF8hC4Gc/merchants"
        },
        "settlements" : {
          "href" : "https://api-test.payline.io:443/identities/IDoicMTU2deqxnNLJF8hC4Gc/settlements"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/identities/IDoicMTU2deqxnNLJF8hC4Gc/authorizations"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/identities/IDoicMTU2deqxnNLJF8hC4Gc/transfers"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/identities/IDoicMTU2deqxnNLJF8hC4Gc/payment_instruments"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/identities/IDoicMTU2deqxnNLJF8hC4Gc/disputes"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    }, {
      "id" : "ID5cjmTxF18LsLnmiMs7oBrg",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Petes Coffee",
        "business_type" : "TAX_EXEMPT_ORGANIZATION",
        "doing_business_as" : "Petes Coffee",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.PetesCoffee.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PUBLIC",
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Petes Coffee"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2017-04-24T20:22:44.73Z",
      "updated_at" : "2017-04-24T20:22:44.73Z",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/identities/ID5cjmTxF18LsLnmiMs7oBrg"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/identities/ID5cjmTxF18LsLnmiMs7oBrg/verifications"
        },
        "merchants" : {
          "href" : "https://api-test.payline.io:443/identities/ID5cjmTxF18LsLnmiMs7oBrg/merchants"
        },
        "settlements" : {
          "href" : "https://api-test.payline.io:443/identities/ID5cjmTxF18LsLnmiMs7oBrg/settlements"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/identities/ID5cjmTxF18LsLnmiMs7oBrg/authorizations"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/identities/ID5cjmTxF18LsLnmiMs7oBrg/transfers"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/identities/ID5cjmTxF18LsLnmiMs7oBrg/payment_instruments"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/identities/ID5cjmTxF18LsLnmiMs7oBrg/disputes"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    }, {
      "id" : "IDN8RwVqDs9hd1zrbBiBKCo",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Dunder Mifflin",
        "business_type" : "INTERNATIONAL_ORGANIZATION",
        "doing_business_as" : "Dunder Mifflin",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.DunderMifflin.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PRIVATE",
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Dunder Mifflin"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2017-04-24T20:22:44.26Z",
      "updated_at" : "2017-04-24T20:22:44.26Z",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/identities/IDN8RwVqDs9hd1zrbBiBKCo"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/identities/IDN8RwVqDs9hd1zrbBiBKCo/verifications"
        },
        "merchants" : {
          "href" : "https://api-test.payline.io:443/identities/IDN8RwVqDs9hd1zrbBiBKCo/merchants"
        },
        "settlements" : {
          "href" : "https://api-test.payline.io:443/identities/IDN8RwVqDs9hd1zrbBiBKCo/settlements"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/identities/IDN8RwVqDs9hd1zrbBiBKCo/authorizations"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/identities/IDN8RwVqDs9hd1zrbBiBKCo/transfers"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/identities/IDN8RwVqDs9hd1zrbBiBKCo/payment_instruments"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/identities/IDN8RwVqDs9hd1zrbBiBKCo/disputes"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    }, {
      "id" : "IDojTbjDr5meZvTy8Z9hdsVH",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Dunder Mifflin",
        "business_type" : "ASSOCIATION_ESTATE_TRUST",
        "doing_business_as" : "Dunder Mifflin",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.DunderMifflin.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PRIVATE",
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Dunder Mifflin"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2017-04-24T20:22:43.84Z",
      "updated_at" : "2017-04-24T20:22:43.84Z",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/identities/IDojTbjDr5meZvTy8Z9hdsVH"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/identities/IDojTbjDr5meZvTy8Z9hdsVH/verifications"
        },
        "merchants" : {
          "href" : "https://api-test.payline.io:443/identities/IDojTbjDr5meZvTy8Z9hdsVH/merchants"
        },
        "settlements" : {
          "href" : "https://api-test.payline.io:443/identities/IDojTbjDr5meZvTy8Z9hdsVH/settlements"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/identities/IDojTbjDr5meZvTy8Z9hdsVH/authorizations"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/identities/IDojTbjDr5meZvTy8Z9hdsVH/transfers"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/identities/IDojTbjDr5meZvTy8Z9hdsVH/payment_instruments"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/identities/IDojTbjDr5meZvTy8Z9hdsVH/disputes"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    }, {
      "id" : "IDf4kZEjgbbkDAJkAHLbwEkd",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Prestige World Wide",
        "business_type" : "PARTNERSHIP",
        "doing_business_as" : "Prestige World Wide",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.PrestigeWorldWide.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PRIVATE",
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Prestige World Wide"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2017-04-24T20:22:43.36Z",
      "updated_at" : "2017-04-24T20:22:43.36Z",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/identities/IDf4kZEjgbbkDAJkAHLbwEkd"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/identities/IDf4kZEjgbbkDAJkAHLbwEkd/verifications"
        },
        "merchants" : {
          "href" : "https://api-test.payline.io:443/identities/IDf4kZEjgbbkDAJkAHLbwEkd/merchants"
        },
        "settlements" : {
          "href" : "https://api-test.payline.io:443/identities/IDf4kZEjgbbkDAJkAHLbwEkd/settlements"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/identities/IDf4kZEjgbbkDAJkAHLbwEkd/authorizations"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/identities/IDf4kZEjgbbkDAJkAHLbwEkd/transfers"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/identities/IDf4kZEjgbbkDAJkAHLbwEkd/payment_instruments"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/identities/IDf4kZEjgbbkDAJkAHLbwEkd/disputes"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    }, {
      "id" : "IDqz6NLfgfC9tUN7tzweNRAM",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Petes Coffee",
        "business_type" : "LIMITED_LIABILITY_COMPANY",
        "doing_business_as" : "Petes Coffee",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.PetesCoffee.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PRIVATE",
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Petes Coffee"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2017-04-24T20:22:42.91Z",
      "updated_at" : "2017-04-24T20:22:42.91Z",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/identities/IDqz6NLfgfC9tUN7tzweNRAM"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/identities/IDqz6NLfgfC9tUN7tzweNRAM/verifications"
        },
        "merchants" : {
          "href" : "https://api-test.payline.io:443/identities/IDqz6NLfgfC9tUN7tzweNRAM/merchants"
        },
        "settlements" : {
          "href" : "https://api-test.payline.io:443/identities/IDqz6NLfgfC9tUN7tzweNRAM/settlements"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/identities/IDqz6NLfgfC9tUN7tzweNRAM/authorizations"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/identities/IDqz6NLfgfC9tUN7tzweNRAM/transfers"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/identities/IDqz6NLfgfC9tUN7tzweNRAM/payment_instruments"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/identities/IDqz6NLfgfC9tUN7tzweNRAM/disputes"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    }, {
      "id" : "IDvpYqDgBkTB8hWAwXdfDqEp",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Golds Gym",
        "business_type" : "CORPORATION",
        "doing_business_as" : "Golds Gym",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.GoldsGym.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PRIVATE",
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Golds Gym"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2017-04-24T20:22:42.38Z",
      "updated_at" : "2017-04-24T20:22:42.38Z",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/identities/IDvpYqDgBkTB8hWAwXdfDqEp"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/identities/IDvpYqDgBkTB8hWAwXdfDqEp/verifications"
        },
        "merchants" : {
          "href" : "https://api-test.payline.io:443/identities/IDvpYqDgBkTB8hWAwXdfDqEp/merchants"
        },
        "settlements" : {
          "href" : "https://api-test.payline.io:443/identities/IDvpYqDgBkTB8hWAwXdfDqEp/settlements"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/identities/IDvpYqDgBkTB8hWAwXdfDqEp/authorizations"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/identities/IDvpYqDgBkTB8hWAwXdfDqEp/transfers"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/identities/IDvpYqDgBkTB8hWAwXdfDqEp/payment_instruments"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/identities/IDvpYqDgBkTB8hWAwXdfDqEp/disputes"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    }, {
      "id" : "ID8dfS5cFQYW2Ckee7BvVR4R",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Prestige World Wide",
        "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
        "doing_business_as" : "Prestige World Wide",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.PrestigeWorldWide.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PRIVATE",
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Prestige World Wide"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      },
      "created_at" : "2017-04-24T20:22:41.81Z",
      "updated_at" : "2017-04-24T20:22:41.81Z",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/verifications"
        },
        "merchants" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/merchants"
        },
        "settlements" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/settlements"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/authorizations"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/transfers"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/payment_instruments"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/disputes"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    }, {
      "id" : "IDh8cH5oknmAQ3kHaodJuwZi",
      "entity" : {
        "title" : null,
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "Venmo",
        "business_type" : "LIMITED_LIABILITY_COMPANY",
        "doing_business_as" : "Venmo",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : null,
        "dob" : {
          "day" : 27,
          "month" : 5,
          "year" : 1978
        },
        "max_transaction_amount" : 1200000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : null,
        "annual_card_volume" : 0,
        "has_accepted_credit_cards_previously" : false,
        "incorporation_date" : null,
        "principal_percentage_ownership" : null,
        "short_business_name" : null,
        "ownership_type" : null,
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : null
      },
      "tags" : {
        "application_name" : "Venmo"
      },
      "created_at" : "2017-04-24T20:22:38.66Z",
      "updated_at" : "2017-04-24T20:22:38.67Z",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/identities/IDh8cH5oknmAQ3kHaodJuwZi"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/identities/IDh8cH5oknmAQ3kHaodJuwZi/verifications"
        },
        "merchants" : {
          "href" : "https://api-test.payline.io:443/identities/IDh8cH5oknmAQ3kHaodJuwZi/merchants"
        },
        "settlements" : {
          "href" : "https://api-test.payline.io:443/identities/IDh8cH5oknmAQ3kHaodJuwZi/settlements"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/identities/IDh8cH5oknmAQ3kHaodJuwZi/authorizations"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/identities/IDh8cH5oknmAQ3kHaodJuwZi/transfers"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/identities/IDh8cH5oknmAQ3kHaodJuwZi/payment_instruments"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/identities/IDh8cH5oknmAQ3kHaodJuwZi/disputes"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io/identities?offset=0&limit=20&sort=created_at,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 10
  }
}

HTTP Request

GET https://api-test.payline.io/identities/

Update an Identity

curl https://api-test.payline.io/identities/ID8dfS5cFQYW2Ckee7BvVR4R \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -X PUT \
    -d '
  {
      "tags": {
          "key": "value_2"
      }, 
      "entity": {
          "business_phone": "+1 (408) 756-4497", 
          "first_name": "Bernard", 
          "last_name": "Sterling", 
          "title": "CTO", 
          "dob": {
              "year": 1988, 
              "day": 2, 
              "month": 5
          }, 
          "ownership_type": "PRIVATE", 
          "has_accepted_credit_cards_previously": true, 
          "mcc": "0742", 
          "phone": "7144177878", 
          "business_tax_id": "123456789", 
          "max_transaction_amount": 1200000, 
          "principal_percentage_ownership": 50, 
          "doing_business_as": "Dunder Mifflin", 
          "annual_card_volume": 12000000, 
          "default_statement_descriptor": "Dunder Mifflin", 
          "url": "www.DunderMifflin.com", 
          "business_name": "Dunder Mifflin", 
          "personal_address": {
              "city": "San Diego", 
              "country": "USA", 
              "region": "CA", 
              "line2": "Apartment 2", 
              "line1": "712 Douglass St", 
              "postal_code": "94194"
          }, 
          "email": "user@example.org", 
          "tax_id": "999999999"
      }
  }'


<?php




identity = Payline::Identity.retrieve(:id=>"ID8dfS5cFQYW2Ckee7BvVR4R")

identity.entity["first_name"] = "Bernard"
identity.save

Example Response:

{
  "id" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "entity" : {
    "title" : "CTO",
    "first_name" : "Bernard",
    "last_name" : "Sterling",
    "email" : "user@example.org",
    "business_name" : "Dunder Mifflin",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "doing_business_as" : "Dunder Mifflin",
    "phone" : "7144177878",
    "business_phone" : "+1 (408) 756-4497",
    "personal_address" : {
      "line1" : "712 Douglass St",
      "line2" : "Apartment 2",
      "city" : "San Diego",
      "region" : "CA",
      "postal_code" : "94194",
      "country" : "USA"
    },
    "business_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 8",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "mcc" : "0742",
    "dob" : {
      "day" : 2,
      "month" : 5,
      "year" : 1988
    },
    "max_transaction_amount" : 1200000,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : "www.DunderMifflin.com",
    "annual_card_volume" : 12000000,
    "has_accepted_credit_cards_previously" : true,
    "incorporation_date" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "principal_percentage_ownership" : 50,
    "short_business_name" : null,
    "ownership_type" : "PRIVATE",
    "tax_id_provided" : true,
    "business_tax_id_provided" : true,
    "default_statement_descriptor" : "Dunder Mifflin"
  },
  "tags" : {
    "key" : "value_2"
  },
  "created_at" : "2017-04-24T20:22:41.81Z",
  "updated_at" : "2017-04-24T20:23:05.75Z",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "verifications" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/verifications"
    },
    "merchants" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/merchants"
    },
    "settlements" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/settlements"
    },
    "authorizations" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/authorizations"
    },
    "transfers" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/transfers"
    },
    "payment_instruments" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/payment_instruments"
    },
    "disputes" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R/disputes"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    }
  }
}

Update the information of a previously created Identity. Please note that in the case of merchant accounts this API request alone does not update this information on the underlying processor. To update the merchant’s information on the underlying processor you must update the merchant on the processor.

HTTP Request

POST https://api-test.payline.io/identities

Business-specific Request Arguments

Field Type Description
business_name string, required Merchant’s full legal business name (If INDIVIDUAL_SOLE_PROPRIETORSHIP, please input first name, Full legal last name and middle initial; max 120 characters)
doing_business_as string, required Alternate name of the business. If no other name is used please use the same value for business_name (max 60 characters)
business_type string, required Please select one of the following values: INDIVIDUAL_SOLE_PROPRIETORSHIP, CORPORATION, LIMITED_LIABILITY_COMPANY, PARTNERSHIP, ASSOCIATION_ESTATE_TRUST, TAX_EXEMPT_ORGANIZATION, INTERNATIONAL_ORGANIZATION, GOVERNMENT_AGENCY
business_tax_id string, required Nine digit Tax Identification Number (TIN), Employer Identification Number (EIN) or if the business_type is INDIVIDUAL_SOLE_PROPRIETORSHIP and a Tax ID is not available, the principal’s Social Security Number (SSN)
url string, required Merchant’s publicly available website (max 100 characters)
business_phone string, required Customer service phone number where the merchant can be reached (max 10 characters)
incorporation_date object, required Date company was founded (See below for a full list of the child attributes)
business_address object, required Primary address for the legal entity (Full description of child attributes below)
ownership_type string, required Values can be either PUBLIC to indicate a publicly traded company or PRIVATE for privately held businesses

Principal-specific Request Arguments

(i.e. authorized representative or primary contact responsible for the account)

Field Type Description
first_name string, required Full legal first name of the merchant’s principal representative (max 20 characters)
last_name string, required Full legal last name of the merchant’s principal representative (max 20 characters)
title string, required Principal’s corporate title or role (i.e. Chief Executive Officer, CFO, etc.; max 60 characters)
principal_percentage_ownership integer, required Percentage of company owned by the principal (min 0; max 100)
tax_id string, required Nine digit Social Security Number (SSN) for the principal
dob object, required Principal’s date of birth (Full description of child attributes below)
phone string, required Principal’s phone number (max 10 characters)
email string, required Principal’s email address where they can be reached (max 100 characters)
personal_address object, required Principal’s personal home address. This field is used for identity verification purposes (Full description of child attributes below)

Processing-specific Request Arguments

Field Type Description
default_statement_descriptor string, required Billing descriptor displayed on the buyer’s bank or card statement (Length must be between 1 and 20 characters)
annual_card_volume integer, required Approximate annual credit card sales expected to be processed in cents by this merchant (max 23 characters)
max_transaction_amount integer, required Maximum amount that can be transacted for a single transaction in cents (max 12 characters)
mcc string, required Merchant Category Code (MCC) that this merchant will be classified under
has_accepted_credit_cards_previously boolean, optional Defaults to false if not passed

Address-object Request Arguments

Field Type Description
line1 string, optional First line of the address (max 60 characters)
line2 string, optional Second line of the address (max 60 characters)
city string, required City (max 20 characters)
region string, optional 2-letter State code
postal_code string, optional Zip or Postal code (max 7 characters)
country string, optional 3-Letter Country code

Incorporation Date-object Request Arguments

Field Type Description
day integer, required Day business was incorporated (between 1 and 31)
month integer, required Month business was incorporated (between 1 and 12)
year integer, required Year business was incorporated (4-digit)

DOB-object Request Arguments

Field Type Description
day integer, required Day of birth (between 1 and 31)
month integer, required Month of birth (between 1 and 12)
year integer, required Year of birth (4-digit)

Provision a Merchant


curl https://api-test.payline.io/identities/ID8dfS5cFQYW2Ckee7BvVR4R/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "processor": null, 
      "tags": {
          "key_2": "value_2"
      }
  }'



import io.payline.payments.processing.client.model.Merchant;

Merchant merchant = identity.provisionMerchantOn(Merchant.builder().build());

<?php
use Payline\Resources\Identity;
use Payline\Resources\Merchant;

$identity = Identity::retrieve('ID8dfS5cFQYW2Ckee7BvVR4R');

$merchant = $identity->provisionMerchantOn(new Merchant());



from payline.resources import Identity
from payline.resources import Merchant

identity = Identity.get(id="ID8dfS5cFQYW2Ckee7BvVR4R")
merchant = identity.provision_merchant_on(Merchant())

identity = Payline::Identity.retrieve(:id=>"ID8dfS5cFQYW2Ckee7BvVR4R")

merchant = identity.provision_merchant

Example Response:

{
  "id" : "MUmCHstoi1n9eERezsZuzxa6",
  "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "verification" : "VI4Bcyya4EAGiZhCkJnWmbtY",
  "merchant_profile" : "MPgm1QRhcy8tY144m5vC3tNs",
  "processor" : "DUMMY_V1",
  "processing_enabled" : false,
  "settlement_enabled" : false,
  "tags" : { },
  "created_at" : "2017-04-24T20:22:47.31Z",
  "updated_at" : "2017-04-24T20:22:47.31Z",
  "onboarding_state" : "PROVISIONING",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/merchants/MUmCHstoi1n9eERezsZuzxa6"
    },
    "identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "verifications" : {
      "href" : "https://api-test.payline.io:443/merchants/MUmCHstoi1n9eERezsZuzxa6/verifications"
    },
    "merchant_profile" : {
      "href" : "https://api-test.payline.io:443/merchant_profiles/MPgm1QRhcy8tY144m5vC3tNs"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "verification" : {
      "href" : "https://api-test.payline.io:443/verifications/VI4Bcyya4EAGiZhCkJnWmbtY"
    }
  }
}

Provision a Merchant for a previously created Identity resource to begin transacting on their behalf.

Merchant resources can have 3 potential states:

  1. PROVISIONING: Request is pending (state will typically change after two minutes)

  2. APPROVED: Merchant has been approved and can begin processing

  3. REJECTED: Merchant was rejected by the processor either because the collected underwriting information was invalid or it failed one a number of regulatory and compliance checks (e.g. KYC, OFAC or MATCH)

HTTP Request

POST https://api-test.payline.io/identities/identity_id/merchants

URL Parameters

Parameter Description
identity_id ID of the Identity

Merchants

A Merchant resource represents a business’s merchant account on a processor. In other words, any web service that connects buyers (i.e. customers) and sellers (i.e. merchants).

Provision a Merchant

curl https://api-test.payline.io/identities/ID8dfS5cFQYW2Ckee7BvVR4R/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "processor": null, 
      "tags": {
          "key_2": "value_2"
      }
  }'

import io.payline.payments.processing.client.model.Merchant;

Merchant merchant = identity.provisionMerchantOn(Merchant.builder().build());

<?php
use Payline\Resources\Identity;
use Payline\Resources\Merchant;

$identity = Identity::retrieve('ID8dfS5cFQYW2Ckee7BvVR4R');

$merchant = $identity->provisionMerchantOn(new Merchant());



from payline.resources import Identity
from payline.resources import Merchant

identity = Identity.get(id="ID8dfS5cFQYW2Ckee7BvVR4R")
merchant = identity.provision_merchant_on(Merchant())

identity = Payline::Identity.retrieve(:id => "MUmCHstoi1n9eERezsZuzxa6")

merchant = identity.provision_merchant

Example Response:

{
  "id" : "MUmCHstoi1n9eERezsZuzxa6",
  "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "verification" : "VI4Bcyya4EAGiZhCkJnWmbtY",
  "merchant_profile" : "MPgm1QRhcy8tY144m5vC3tNs",
  "processor" : "DUMMY_V1",
  "processing_enabled" : false,
  "settlement_enabled" : false,
  "tags" : { },
  "created_at" : "2017-04-24T20:22:47.31Z",
  "updated_at" : "2017-04-24T20:22:47.31Z",
  "onboarding_state" : "PROVISIONING",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/merchants/MUmCHstoi1n9eERezsZuzxa6"
    },
    "identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "verifications" : {
      "href" : "https://api-test.payline.io:443/merchants/MUmCHstoi1n9eERezsZuzxa6/verifications"
    },
    "merchant_profile" : {
      "href" : "https://api-test.payline.io:443/merchant_profiles/MPgm1QRhcy8tY144m5vC3tNs"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "verification" : {
      "href" : "https://api-test.payline.io:443/verifications/VI4Bcyya4EAGiZhCkJnWmbtY"
    }
  }
}

Provision a Merchant for a previously created Identity resource to begin transacting on their behalf.

Merchant resources can have 3 potential onboarding_states:

  1. PROVISIONING: Request is pending (state will typically change after two minutes)

    • processing_enabled: False
    • settlement_enabled: False
  2. APPROVED: Merchant has been approved and can begin processing

    • processing_enabled: True
    • settlement_enabled: True
  3. REJECTED: Merchant was rejected by the processor either because the collected information was invalid or it failed one of a number of regulatory and/or compliance checks (e.g. KYC, OFAC or MATCH)

    • processing_enabled: False
    • settlement_enabled: False

HTTP Request

POST https://api-test.payline.io/identities/:IDENTITY_ID/merchants

URL Parameters

Parameter Description
:IDENTITY_ID ID of the Identity

Retrieve a Merchant

curl https://api-test.payline.io/merchants/MUmCHstoi1n9eERezsZuzxa6 \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3

import io.payline.payments.processing.client.model.Merchant;

Merchant merchant = client.merchantsClient().fetch("MUmCHstoi1n9eERezsZuzxa6");

<?php
use Payline\Resources\Merchant;

$merchant = Merchant::retrieve('MUmCHstoi1n9eERezsZuzxa6');



from payline.resources import Merchant
merchant = Merchant.get(id="MUmCHstoi1n9eERezsZuzxa6")

merchant = Payline::Merchant.retrieve(:id => "MUmCHstoi1n9eERezsZuzxa6")

Example Response:

{
  "id" : "MUmCHstoi1n9eERezsZuzxa6",
  "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "verification" : null,
  "merchant_profile" : "MPgm1QRhcy8tY144m5vC3tNs",
  "processor" : "DUMMY_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "tags" : { },
  "created_at" : "2017-04-24T20:22:47.28Z",
  "updated_at" : "2017-04-24T20:22:47.40Z",
  "onboarding_state" : "APPROVED",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/merchants/MUmCHstoi1n9eERezsZuzxa6"
    },
    "identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "verifications" : {
      "href" : "https://api-test.payline.io:443/merchants/MUmCHstoi1n9eERezsZuzxa6/verifications"
    },
    "merchant_profile" : {
      "href" : "https://api-test.payline.io:443/merchant_profiles/MPgm1QRhcy8tY144m5vC3tNs"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    }
  }
}

HTTP Request

GET https://api-test.payline.io/merchants/:MERCHANT_ID

URL Parameters

Parameter Description
:MERCHANT_ID ID of the Merchant

Reattempt Merchant Provisioning

curl https://api-test.payline.io/merchants/MUmCHstoi1n9eERezsZuzxa6/verifications \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '{}'
Merchant merchant = client.merchantsClient().fetch("MUmCHstoi1n9eERezsZuzxa6");
Verification verification = merchant.verify(
  Verification.builder().build()
);
<?php
use Payline\Resources\Merchant;
use Payline\Resources\Verification;

$merchant = Merchant::retrieve('MUmCHstoi1n9eERezsZuzxa6');
$verification = new Verification();
$verification = $merchant->verifyOn($verification);



merchant = Payline::Merchant.retrieve(:id => "MUmCHstoi1n9eERezsZuzxa6")

verification = merchant.verify

Example Response:

{
  "id" : "VI424H7Sp8PBCgcEwkg3ivU7",
  "tags" : { },
  "messages" : [ ],
  "raw" : null,
  "processor" : "DUMMY_V1",
  "state" : "PENDING",
  "created_at" : "2017-04-24T20:23:06.33Z",
  "updated_at" : "2017-04-24T20:23:06.35Z",
  "trace_id" : "999918bf-d626-456b-96f8-8d3e881be267",
  "payment_instrument" : null,
  "merchant" : "MUmCHstoi1n9eERezsZuzxa6",
  "identity" : null,
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/verifications/VI424H7Sp8PBCgcEwkg3ivU7"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "merchant" : {
      "href" : "https://api-test.payline.io:443/merchants/MUmCHstoi1n9eERezsZuzxa6"
    }
  }
}

Re-attempt provisioning a Merchant account on a processor if the previous attempt returned a FAILED onboarding_state.

HTTP Request

POST https://api-test.payline.io/merchants/:MERCHANT_ID/verifications

URL Parameters

Parameter Description
:MERCHANT_ID ID of the Merchant

Update Info on Processor

curl https://api-test.payline.io/merchants/MUmCHstoi1n9eERezsZuzxa6/verifications \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '{}'


<?php
use Payline\Resources\Merchant;
use Payline\Resources\Verification;

$merchant = Merchant::retrieve('MUmCHstoi1n9eERezsZuzxa6');
$verification = new Verification();
$verification = $merchant->verifyOn($verification);



merchant = Payline::Merchant.retrieve(:id => "MUmCHstoi1n9eERezsZuzxa6")

verification = merchant.verify

Example Response:

{
  "id" : "VI424H7Sp8PBCgcEwkg3ivU7",
  "tags" : { },
  "messages" : [ ],
  "raw" : null,
  "processor" : "DUMMY_V1",
  "state" : "PENDING",
  "created_at" : "2017-04-24T20:23:06.33Z",
  "updated_at" : "2017-04-24T20:23:06.35Z",
  "trace_id" : "999918bf-d626-456b-96f8-8d3e881be267",
  "payment_instrument" : null,
  "merchant" : "MUmCHstoi1n9eERezsZuzxa6",
  "identity" : null,
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/verifications/VI424H7Sp8PBCgcEwkg3ivU7"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "merchant" : {
      "href" : "https://api-test.payline.io:443/merchants/MUmCHstoi1n9eERezsZuzxa6"
    }
  }
}

Update Identity information (e.g. default_statement_descriptor, KYC info, etc.) on the underlying processor.

HTTP Request

POST https://api-test.payline.io/merchants/:MERCHANT_ID/verifications

URL Parameters

Parameter Description
:MERCHANT_ID ID of the Merchant

List all Merchants

curl https://api-test.payline.io/merchants/ \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3


<?php
use Payline\Resources\Merchant;

$merchants = Merchant::getPagination("/merchants");




from payline.resources import Merchant
merchant = Merchant.get()

merchants = Payline::Merchant.retrieve

Example Response:

{
  "_embedded" : {
    "merchants" : [ {
      "id" : "MUmCHstoi1n9eERezsZuzxa6",
      "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
      "verification" : null,
      "merchant_profile" : "MPgm1QRhcy8tY144m5vC3tNs",
      "processor" : "DUMMY_V1",
      "processing_enabled" : true,
      "settlement_enabled" : true,
      "tags" : { },
      "created_at" : "2017-04-24T20:22:47.28Z",
      "updated_at" : "2017-04-24T20:22:47.40Z",
      "onboarding_state" : "APPROVED",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/merchants/MUmCHstoi1n9eERezsZuzxa6"
        },
        "identity" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/merchants/MUmCHstoi1n9eERezsZuzxa6/verifications"
        },
        "merchant_profile" : {
          "href" : "https://api-test.payline.io:443/merchant_profiles/MPgm1QRhcy8tY144m5vC3tNs"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io/merchants?offset=0&limit=20&sort=created_at,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 1
  }
}

HTTP Request

GET https://api-test.payline.io/merchants/

List Merchant Verifications

curl https://api-test.payline.io/merchants/MUmCHstoi1n9eERezsZuzxa6/verifications \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3


<?php
use Payline\Resources\Merchant;
use Payline\Resources\Verification;

$merchant = Merchant::retrieve('MUmCHstoi1n9eERezsZuzxa6');
$verifications = Verification::getPagination($merchant->getHref("verifications"));





merchant = Payline::Merchant.retrieve(:id => "MUmCHstoi1n9eERezsZuzxa6")
verifications = merchant.verifications

Example Response:

{
  "_embedded" : {
    "verifications" : [ {
      "id" : "VI4Bcyya4EAGiZhCkJnWmbtY",
      "tags" : {
        "key_2" : "value_2"
      },
      "messages" : [ ],
      "raw" : "RawDummyMerchantUnderwriteResult",
      "processor" : "DUMMY_V1",
      "state" : "SUCCEEDED",
      "created_at" : "2017-04-24T20:22:47.28Z",
      "updated_at" : "2017-04-24T20:22:47.44Z",
      "trace_id" : "098f8611-690b-4687-b09f-3bd288bb50f9",
      "payment_instrument" : null,
      "merchant" : "MUmCHstoi1n9eERezsZuzxa6",
      "identity" : null,
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/verifications/VI4Bcyya4EAGiZhCkJnWmbtY"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "merchant" : {
          "href" : "https://api-test.payline.io:443/merchants/MUmCHstoi1n9eERezsZuzxa6"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io/merchants/MUmCHstoi1n9eERezsZuzxa6/verifications?offset=0&limit=20&sort=created_at,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 1
  }
}

Retrieve all attempts to onboard (i.e. provision) a merchant onto a processor.

HTTP Request

GET https://api-test.payline.io/merchants/:MERCHANT_ID/verifications

URL Parameters

Parameter Description
:MERCHANT_ID ID of the Merchant

Payment Instruments

A Payment Instrument resource represents either a credit card or bank account. A Payment Instrument may be tokenized multiple times and each tokenization produces a unique ID. Each ID may only be associated one time and to only one Identity. Once associated, a Payment Instrument may not be disassociated from an Identity.

Create a Card



curl https://api-test.payline.io/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "name": "Marshall Le", 
      "expiration_year": 2020, 
      "tags": {
          "card_name": "Business Card"
      }, 
      "number": "4957030420210454", 
      "expiration_month": 12, 
      "address": {
          "city": "San Mateo", 
          "country": "USA", 
          "region": "CA", 
          "line2": "Apartment 7", 
          "line1": "741 Douglass St", 
          "postal_code": "94114"
      }, 
      "security_code": "112", 
      "type": "PAYMENT_CARD", 
      "identity": "IDpBkS8wBTAticFPHs4gJnp2"
  }'



import io.payline.payments.processing.client.model.PaymentCard;

PaymentCard paymentCard = PaymentCard.builder()
    .name(Name.parse("Joe Doe"))
    .identity("ID8dfS5cFQYW2Ckee7BvVR4R")
    .expirationMonth(12)
    .expirationYear(2030)
    .number("4111 1111 1111 1111")
    .securityCode("231")
    .build(); 
paymentCard = client.paymentCardsClient().save(paymentCard);

<?php
use Payline\Resources\PaymentCard;
use Payline\Resources\Identity;

$identity = Identity::retrieve('ID8dfS5cFQYW2Ckee7BvVR4R');
$card = new PaymentCard(
  array(
      "name"=> "Marshall Le", 
      "expiration_year"=> 2020, 
      "tags"=> array(
          "card_name"=> "Business Card"
      ), 
      "number"=> "4957030420210454", 
      "expiration_month"=> 12, 
      "address"=> array(
          "city"=> "San Mateo", 
          "country"=> "USA", 
          "region"=> "CA", 
          "line2"=> "Apartment 7", 
          "line1"=> "741 Douglass St", 
          "postal_code"=> "94114"
      ), 
      "security_code"=> "112", 
      "type"=> "PAYMENT_CARD", 
      "identity"=> "IDpBkS8wBTAticFPHs4gJnp2"
  ));
$card = $identity->createPaymentCard($card);



from payline.resources import PaymentCard

card = PaymentCard(**
  {
      "name": "Marshall Le", 
      "expiration_year": 2020, 
      "tags": {
          "card_name": "Business Card"
      }, 
      "number": "4957030420210454", 
      "expiration_month": 12, 
      "address": {
          "city": "San Mateo", 
          "country": "USA", 
          "region": "CA", 
          "line2": "Apartment 7", 
          "line1": "741 Douglass St", 
          "postal_code": "94114"
      }, 
      "security_code": "112", 
      "type": "PAYMENT_CARD", 
      "identity": "IDpBkS8wBTAticFPHs4gJnp2"
  }).save()
card = Payline::PaymentCard.new(
  {
      "name"=> "Marshall Le", 
      "expiration_year"=> 2020, 
      "tags"=> {
          "card_name"=> "Business Card"
      }, 
      "number"=> "4957030420210454", 
      "expiration_month"=> 12, 
      "address"=> {
          "city"=> "San Mateo", 
          "country"=> "USA", 
          "region"=> "CA", 
          "line2"=> "Apartment 7", 
          "line1"=> "741 Douglass St", 
          "postal_code"=> "94114"
      }, 
      "security_code"=> "112", 
      "type"=> "PAYMENT_CARD", 
      "identity"=> "IDpBkS8wBTAticFPHs4gJnp2"
  }).save

Example Response:

{
  "id" : "PIgM6zjoU4nN7PZmGwGMMaf6",
  "fingerprint" : "FPR-410674752",
  "tags" : {
    "card_name" : "Business Card"
  },
  "expiration_month" : 12,
  "expiration_year" : 2020,
  "last_four" : "0454",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : "Marshall Le",
  "address" : {
    "line1" : "741 Douglass St",
    "line2" : "Apartment 7",
    "city" : "San Mateo",
    "region" : "CA",
    "postal_code" : "94114",
    "country" : "USA"
  },
  "address_verification" : "UNKNOWN",
  "security_code_verification" : "UNKNOWN",
  "created_at" : "2017-04-24T20:22:48.65Z",
  "updated_at" : "2017-04-24T20:22:48.65Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDpBkS8wBTAticFPHs4gJnp2",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6"
    },
    "authorizations" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6/authorizations"
    },
    "identity" : {
      "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2"
    },
    "transfers" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6/transfers"
    },
    "verifications" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6/verifications"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "updates" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6/updates"
    }
  }
}

Please review our guide on how to tokenize cards via the embedded tokenization form

HTTP Request

POST https://api-test.payline.io/payment_instruments

Request Arguments

Field Type Description
identity string, required ID of the Identity that the card should be associated
type string, required Type of Payment Instrument (for cards input PAYMENT_CARD)
number string, required Credit card account number
security_code string, optional The 3-4 digit security code for the card (i.e. CVV code)
expiration_month integer, required Expiration month (e.g. 12 for December)
expiration_year integer, required 4-digit expiration year
name string, optional Full name of the registered card holder
address object, optional Billing address (Full description of child attributes below)

Address-object Request Arguments

Field Type Description
line1 string, optional First line of the address (max 60 characters)
line2 string, optional Second line of the address (max 60 characters)
city string, optional City (max 20 characters)
region string, optional 2-letter State code
postal_code string, optional Zip or Postal code (max 7 characters)
country string, optional 3-Letter Country code

Create a Bank Account


curl https://api-test.payline.io/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "account_type": "SAVINGS", 
      "name": "Fran Lemke", 
      "tags": {
          "Bank Account": "Company Account"
      }, 
      "country": "USA", 
      "bank_code": "123123123", 
      "account_number": "123123123", 
      "type": "BANK_ACCOUNT", 
      "identity": "ID8dfS5cFQYW2Ckee7BvVR4R"
  }'



import io.payline.payments.processing.client.model.BankAccount;
import io.payline.payments.processing.client.model.Name;

BankAccount bankAccount = client.bankAccountsClient().save(
  BankAccount.builder()
    .name(Name.parse("Billy Bob Thorton III"))
    .identity("ID8dfS5cFQYW2Ckee7BvVR4R")
    .accountNumber("84012312415")
    .bankCode("840123124")
    .accountType(BankAccountType.SAVINGS)
    .companyName("company name")
    .country("USA")
    .currency("USD")
    .build()
);

<?php
use Payline\Resources\Identity;
use Payline\Resources\BankAccount;

$identity = Identity::retrieve('ID8dfS5cFQYW2Ckee7BvVR4R');
$bank_account = new BankAccount(
  array(
      "account_type"=> "SAVINGS", 
      "name"=> "Fran Lemke", 
      "tags"=> array(
          "Bank Account"=> "Company Account"
      ), 
      "country"=> "USA", 
      "bank_code"=> "123123123", 
      "account_number"=> "123123123", 
      "type"=> "BANK_ACCOUNT", 
      "identity"=> "ID8dfS5cFQYW2Ckee7BvVR4R"
  ));
$bank_account = $identity->createBankAccount($bank_account);


from payline.resources import BankAccount

bank_account = BankAccount(**
  {
      "account_type": "SAVINGS", 
      "name": "Fran Lemke", 
      "tags": {
          "Bank Account": "Company Account"
      }, 
      "country": "USA", 
      "bank_code": "123123123", 
      "account_number": "123123123", 
      "type": "BANK_ACCOUNT", 
      "identity": "ID8dfS5cFQYW2Ckee7BvVR4R"
  }).save()
bank_account = Payline::BankAccount.new(
  {
      "account_type"=> "SAVINGS", 
      "name"=> "Fran Lemke", 
      "tags"=> {
          "Bank Account"=> "Company Account"
      }, 
      "country"=> "USA", 
      "bank_code"=> "123123123", 
      "account_number"=> "123123123", 
      "type"=> "BANK_ACCOUNT", 
      "identity"=> "ID8dfS5cFQYW2Ckee7BvVR4R"
  }).save

Example Response:

{
  "id" : "PIhGEt5UWQXxrvNba8bc6jxg",
  "fingerprint" : "FPR-1215770130",
  "tags" : {
    "Bank Account" : "Company Account"
  },
  "bank_code" : "123123123",
  "country" : "USA",
  "masked_account_number" : "XXXXX3123",
  "name" : "Fran Lemke",
  "account_type" : "SAVINGS",
  "created_at" : "2017-04-24T20:22:45.94Z",
  "updated_at" : "2017-04-24T20:22:45.94Z",
  "instrument_type" : "BANK_ACCOUNT",
  "type" : "BANK_ACCOUNT",
  "currency" : "USD",
  "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIhGEt5UWQXxrvNba8bc6jxg"
    },
    "authorizations" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIhGEt5UWQXxrvNba8bc6jxg/authorizations"
    },
    "identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "transfers" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIhGEt5UWQXxrvNba8bc6jxg/transfers"
    },
    "verifications" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIhGEt5UWQXxrvNba8bc6jxg/verifications"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    }
  }
}

HTTP Request

POST https://api-test.payline.io/payment_instruments

Request Arguments

Field Type Description
account_number string, required Bank account number
bank_code string, required Bank routing number
type string, required Type of Payment Instrument (for bank accounts use BANK_ACCOUNT)
identity string, required ID for the Identity resource which the account is associated
account_type string, required Either CHECKING or SAVINGS
name string, required Account owner’s full name (max 40 characters)

Associate a Token

curl https://api-test.payline.io/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "token": "TKianXsx7RnMPpVZ8JMEE4D6", 
      "type": "TOKEN", 
      "identity": "ID8dfS5cFQYW2Ckee7BvVR4R"
  }'


import io.payline.payments.processing.client.model.PaymentCard;
import io.payline.payments.processing.client.model.PaymentCardToken;

PaymentCard card = client.paymentCardsClient().associateToken(
    PaymentCardToken.builder()
            .token("TKianXsx7RnMPpVZ8JMEE4D6")
            .identity("ID8dfS5cFQYW2Ckee7BvVR4R")
    .build()
);
<?php
use Payline\Resources\PaymentInstrument;

$card = new PaymentInstrument(
  array(
      "token"=> "TKianXsx7RnMPpVZ8JMEE4D6", 
      "type"=> "TOKEN", 
      "identity"=> "ID8dfS5cFQYW2Ckee7BvVR4R"
  ));
$card = $card->save();



from payline.resources import PaymentInstrument

payment_instrument = PaymentInstrument(**
  {
      "token": "TKianXsx7RnMPpVZ8JMEE4D6", 
      "type": "TOKEN", 
      "identity": "ID8dfS5cFQYW2Ckee7BvVR4R"
  }).save()
card = Payline::PaymentInstrument.new(
  {
      "token"=> "TKianXsx7RnMPpVZ8JMEE4D6", 
      "type"=> "TOKEN", 
      "identity"=> "ID8dfS5cFQYW2Ckee7BvVR4R"
  }).save

Example Response:

{
  "id" : "PIianXsx7RnMPpVZ8JMEE4D6",
  "fingerprint" : "FPR1145082950",
  "tags" : { },
  "expiration_month" : 12,
  "expiration_year" : 2020,
  "last_four" : "4242",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : null,
  "address" : {
    "line1" : "741 Douglass St",
    "line2" : "Apartment 7",
    "city" : "San Mateo",
    "region" : "CA",
    "postal_code" : "94114",
    "country" : "USA"
  },
  "address_verification" : "UNKNOWN",
  "security_code_verification" : "UNKNOWN",
  "created_at" : "2017-04-24T20:22:55.51Z",
  "updated_at" : "2017-04-24T20:22:55.51Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6"
    },
    "authorizations" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6/authorizations"
    },
    "identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "transfers" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6/transfers"
    },
    "verifications" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6/verifications"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "updates" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6/updates"
    }
  }
}

Associate the newly tokenized card or bank with the instrument owner’s Identity.

HTTP Request

POST https://api-test.payline.io/payment_instruments

Request Arguments

Field Type Description
token string, required ID for the Token that was returned via the tokenization client or hosted iframe
type string, required Must pass TOKEN as the value
identity string, required ID for the Identity resource which the account is to be associated

Fetch a Bank Account

curl https://api-test.payline.io/payment_instruments/PIhGEt5UWQXxrvNba8bc6jxg \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \


import io.payline.payments.processing.client.model.PaymentCard;

BankAccount bankAccount = client.bankAccountsClient().fetch("PIhGEt5UWQXxrvNba8bc6jxg")

<?php
use Payline\Resources\PaymentInstrument;

$bank_account = PaymentInstrument::retrieve('PIhGEt5UWQXxrvNba8bc6jxg');




bank_account = Payline::BankAccount.retrieve(:id=> "PIhGEt5UWQXxrvNba8bc6jxg")

Example Response:

{
  "id" : "PIhGEt5UWQXxrvNba8bc6jxg",
  "fingerprint" : "FPR-1215770130",
  "tags" : {
    "Display Name" : "Updated Field"
  },
  "bank_code" : "123123123",
  "country" : "USA",
  "masked_account_number" : "XXXXX3123",
  "name" : "Fran Lemke",
  "account_type" : "SAVINGS",
  "created_at" : "2017-04-24T20:22:45.91Z",
  "updated_at" : "2017-04-24T20:22:46.71Z",
  "instrument_type" : "BANK_ACCOUNT",
  "type" : "BANK_ACCOUNT",
  "currency" : "USD",
  "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIhGEt5UWQXxrvNba8bc6jxg"
    },
    "authorizations" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIhGEt5UWQXxrvNba8bc6jxg/authorizations"
    },
    "identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "transfers" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIhGEt5UWQXxrvNba8bc6jxg/transfers"
    },
    "verifications" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIhGEt5UWQXxrvNba8bc6jxg/verifications"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    }
  }
}

Fetch a previously created Payment Instrument that is of type BANK_ACCOUNT

HTTP Request

GET https://api-test.payline.io/payment_instruments/:PAYMENT_INSTRUMENT_ID

URL Parameters

Parameter Description
:PAYMENT_INSTRUMENT_ID ID of the Payment Instrument

Fetch a Credit Card

curl https://api-test.payline.io/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6 \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \


import io.payline.payments.processing.client.model.PaymentCard;

PaymentCard paymentCard = client.paymentCardsClient().fetch("PIgM6zjoU4nN7PZmGwGMMaf6")

<?php
use Payline\Resources\PaymentInstrument;

$card = PaymentInstrument::retrieve('PIgM6zjoU4nN7PZmGwGMMaf6');




card = Payline::PaymentCard.retrieve(:id=> "PIgM6zjoU4nN7PZmGwGMMaf6")


Example Response:

{
  "id" : "PIgM6zjoU4nN7PZmGwGMMaf6",
  "fingerprint" : "FPR-410674752",
  "tags" : {
    "card_name" : "Business Card"
  },
  "expiration_month" : 12,
  "expiration_year" : 2020,
  "last_four" : "0454",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : "Marshall Le",
  "address" : {
    "line1" : "741 Douglass St",
    "line2" : "Apartment 7",
    "city" : "San Mateo",
    "region" : "CA",
    "postal_code" : "94114",
    "country" : "USA"
  },
  "address_verification" : "POSTAL_CODE_AND_STREET_MATCH",
  "security_code_verification" : "MATCHED",
  "created_at" : "2017-04-24T20:22:48.61Z",
  "updated_at" : "2017-04-24T20:22:53.40Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDpBkS8wBTAticFPHs4gJnp2",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6"
    },
    "authorizations" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6/authorizations"
    },
    "identity" : {
      "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2"
    },
    "transfers" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6/transfers"
    },
    "verifications" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6/verifications"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "updates" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6/updates"
    }
  }
}

Fetch a previously created Payment Instrument that is of type PAYMENT_CARD

HTTP Request

GET https://api-test.payline.io/payment_instruments/:PAYMENT_INSTRUMENT_ID

URL Parameters

Parameter Description
:PAYMENT_INSTRUMENT_ID ID of the Payment Instrument

Check for Card Updates

curl https://api-test.payline.io/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6/updates \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "merchant": "MUmCHstoi1n9eERezsZuzxa6"
  }'


<?php





Example Response:

{
  "id" : "IU9MhAN7EgiU2qWg7PJ1dxJ8",
  "application" : "APoo7cFGmGBiDzRarUMDyAwB",
  "merchant" : "MUmCHstoi1n9eERezsZuzxa6",
  "state" : "PENDING",
  "messages" : [ ],
  "created_at" : "2017-04-24T20:22:57.63Z",
  "updated_at" : "2017-04-24T20:22:57.65Z",
  "payment_instrument" : "PIgM6zjoU4nN7PZmGwGMMaf6",
  "trace_id" : "252e3914-8af4-43cb-a18f-4e0951d56a67",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/updates/IU9MhAN7EgiU2qWg7PJ1dxJ8"
    },
    "payment_instrument" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    }
  }
}

HTTP Request

POST https://api-test.payline.io/payment_instruments/:PAYMENT_INSTRUMENT_ID/updates/

Request Arguments

Field Type Description
:MERCHANT_ID string, required ID of the Merchant
:PAYMENT_INSTRUMENT_ID string, required ID of the Payment Instrument

List all Payment Instruments

curl https://api-test.payline.io/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3
import io.payline.payments.processing.client.model.BankAccount;

client.bankAccountsClient().<Resources<BankAccount>>resourcesIterator()
  .forEachRemaining(baPage -> {
    Collection<BankAccount> bankAccounts = baPage.getContent();
    //do something
  });

<?php
use Payline\Resources\PaymentInstrument;

$paymentinstruments = PaymentInstrument::getPagination("/payment_instruments");





payment_instruments = Payline::PaymentInstruments.retrieve

Example Response:

{
  "_embedded" : {
    "payment_instruments" : [ {
      "id" : "PIianXsx7RnMPpVZ8JMEE4D6",
      "fingerprint" : "FPR1145082950",
      "tags" : { },
      "expiration_month" : 12,
      "expiration_year" : 2020,
      "last_four" : "4242",
      "brand" : "VISA",
      "card_type" : "UNKNOWN",
      "name" : null,
      "address" : {
        "line1" : "741 Douglass St",
        "line2" : "Apartment 7",
        "city" : "San Mateo",
        "region" : "CA",
        "postal_code" : "94114",
        "country" : "USA"
      },
      "address_verification" : "UNKNOWN",
      "security_code_verification" : "UNKNOWN",
      "created_at" : "2017-04-24T20:22:55.47Z",
      "updated_at" : "2017-04-24T20:22:55.47Z",
      "instrument_type" : "PAYMENT_CARD",
      "type" : "PAYMENT_CARD",
      "currency" : "USD",
      "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6/authorizations"
        },
        "identity" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6/transfers"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6/verifications"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "updates" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIianXsx7RnMPpVZ8JMEE4D6/updates"
        }
      }
    }, {
      "id" : "PIhXugCSbMFHDggWrvxJ6Pan",
      "fingerprint" : "FPR-1215770130",
      "tags" : {
        "Bank Account" : "Company Account"
      },
      "bank_code" : "123123123",
      "country" : "USA",
      "masked_account_number" : "XXXXX3123",
      "name" : "Fran Lemke",
      "account_type" : "SAVINGS",
      "created_at" : "2017-04-24T20:22:49.04Z",
      "updated_at" : "2017-04-24T20:22:49.04Z",
      "instrument_type" : "BANK_ACCOUNT",
      "type" : "BANK_ACCOUNT",
      "currency" : "USD",
      "identity" : "IDpBkS8wBTAticFPHs4gJnp2",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIhXugCSbMFHDggWrvxJ6Pan"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIhXugCSbMFHDggWrvxJ6Pan/authorizations"
        },
        "identity" : {
          "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIhXugCSbMFHDggWrvxJ6Pan/transfers"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIhXugCSbMFHDggWrvxJ6Pan/verifications"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    }, {
      "id" : "PIgM6zjoU4nN7PZmGwGMMaf6",
      "fingerprint" : "FPR-410674752",
      "tags" : {
        "card_name" : "Business Card"
      },
      "expiration_month" : 12,
      "expiration_year" : 2020,
      "last_four" : "0454",
      "brand" : "VISA",
      "card_type" : "UNKNOWN",
      "name" : "Marshall Le",
      "address" : {
        "line1" : "741 Douglass St",
        "line2" : "Apartment 7",
        "city" : "San Mateo",
        "region" : "CA",
        "postal_code" : "94114",
        "country" : "USA"
      },
      "address_verification" : "POSTAL_CODE_AND_STREET_MATCH",
      "security_code_verification" : "MATCHED",
      "created_at" : "2017-04-24T20:22:48.61Z",
      "updated_at" : "2017-04-24T20:22:53.40Z",
      "instrument_type" : "PAYMENT_CARD",
      "type" : "PAYMENT_CARD",
      "currency" : "USD",
      "identity" : "IDpBkS8wBTAticFPHs4gJnp2",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6/authorizations"
        },
        "identity" : {
          "href" : "https://api-test.payline.io:443/identities/IDpBkS8wBTAticFPHs4gJnp2"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6/transfers"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6/verifications"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "updates" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6/updates"
        }
      }
    }, {
      "id" : "PIu92KiRkzf4ew2gLs7KxKvv",
      "fingerprint" : "FPR-2042121662",
      "tags" : { },
      "name" : null,
      "created_at" : "2017-04-24T20:22:47.28Z",
      "updated_at" : "2017-04-24T20:22:47.28Z",
      "instrument_type" : "VIRTUAL",
      "type" : "VIRTUAL",
      "currency" : "USD",
      "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIu92KiRkzf4ew2gLs7KxKvv"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIu92KiRkzf4ew2gLs7KxKvv/authorizations"
        },
        "identity" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIu92KiRkzf4ew2gLs7KxKvv/transfers"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIu92KiRkzf4ew2gLs7KxKvv/verifications"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    }, {
      "id" : "PItt4prxF6wCSdH8bKApuKUw",
      "fingerprint" : "FPR-1383578548",
      "tags" : { },
      "name" : null,
      "created_at" : "2017-04-24T20:22:47.28Z",
      "updated_at" : "2017-04-24T20:22:47.28Z",
      "instrument_type" : "VIRTUAL",
      "type" : "VIRTUAL",
      "currency" : "USD",
      "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PItt4prxF6wCSdH8bKApuKUw"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PItt4prxF6wCSdH8bKApuKUw/authorizations"
        },
        "identity" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PItt4prxF6wCSdH8bKApuKUw/transfers"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PItt4prxF6wCSdH8bKApuKUw/verifications"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    }, {
      "id" : "PI4NUUE6FYZ5NMDT2AQ71FRK",
      "fingerprint" : "FPR-1645745263",
      "tags" : { },
      "name" : null,
      "created_at" : "2017-04-24T20:22:47.28Z",
      "updated_at" : "2017-04-24T20:22:47.28Z",
      "instrument_type" : "VIRTUAL",
      "type" : "VIRTUAL",
      "currency" : "USD",
      "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI4NUUE6FYZ5NMDT2AQ71FRK"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI4NUUE6FYZ5NMDT2AQ71FRK/authorizations"
        },
        "identity" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI4NUUE6FYZ5NMDT2AQ71FRK/transfers"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI4NUUE6FYZ5NMDT2AQ71FRK/verifications"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    }, {
      "id" : "PIhGEt5UWQXxrvNba8bc6jxg",
      "fingerprint" : "FPR-1215770130",
      "tags" : {
        "Display Name" : "Updated Field"
      },
      "bank_code" : "123123123",
      "country" : "USA",
      "masked_account_number" : "XXXXX3123",
      "name" : "Fran Lemke",
      "account_type" : "SAVINGS",
      "created_at" : "2017-04-24T20:22:45.91Z",
      "updated_at" : "2017-04-24T20:22:46.71Z",
      "instrument_type" : "BANK_ACCOUNT",
      "type" : "BANK_ACCOUNT",
      "currency" : "USD",
      "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIhGEt5UWQXxrvNba8bc6jxg"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIhGEt5UWQXxrvNba8bc6jxg/authorizations"
        },
        "identity" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIhGEt5UWQXxrvNba8bc6jxg/transfers"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIhGEt5UWQXxrvNba8bc6jxg/verifications"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    }, {
      "id" : "PImLauhzQi9mZv4T17GEY7h7",
      "fingerprint" : "FPR-2042121662",
      "tags" : { },
      "name" : null,
      "created_at" : "2017-04-24T20:22:39.36Z",
      "updated_at" : "2017-04-24T20:22:39.36Z",
      "instrument_type" : "VIRTUAL",
      "type" : "VIRTUAL",
      "currency" : "USD",
      "identity" : "IDjFtXt19dt59nd6jyyF7VuF",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PImLauhzQi9mZv4T17GEY7h7"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PImLauhzQi9mZv4T17GEY7h7/authorizations"
        },
        "identity" : {
          "href" : "https://api-test.payline.io:443/identities/IDjFtXt19dt59nd6jyyF7VuF"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PImLauhzQi9mZv4T17GEY7h7/transfers"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PImLauhzQi9mZv4T17GEY7h7/verifications"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    }, {
      "id" : "PI3gSgQKtpUVUbuRiFcWemfv",
      "fingerprint" : "FPR-2042121662",
      "tags" : { },
      "name" : null,
      "created_at" : "2017-04-24T20:22:39.36Z",
      "updated_at" : "2017-04-24T20:22:39.36Z",
      "instrument_type" : "VIRTUAL",
      "type" : "VIRTUAL",
      "currency" : "USD",
      "identity" : "IDh8cH5oknmAQ3kHaodJuwZi",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI3gSgQKtpUVUbuRiFcWemfv"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI3gSgQKtpUVUbuRiFcWemfv/authorizations"
        },
        "identity" : {
          "href" : "https://api-test.payline.io:443/identities/IDh8cH5oknmAQ3kHaodJuwZi"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI3gSgQKtpUVUbuRiFcWemfv/transfers"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI3gSgQKtpUVUbuRiFcWemfv/verifications"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    }, {
      "id" : "PIiiJ66LJMiYretPh9tcXHXJ",
      "fingerprint" : "FPR-1383578548",
      "tags" : { },
      "name" : null,
      "created_at" : "2017-04-24T20:22:39.36Z",
      "updated_at" : "2017-04-24T20:22:39.36Z",
      "instrument_type" : "VIRTUAL",
      "type" : "VIRTUAL",
      "currency" : "USD",
      "identity" : "IDh8cH5oknmAQ3kHaodJuwZi",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIiiJ66LJMiYretPh9tcXHXJ"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIiiJ66LJMiYretPh9tcXHXJ/authorizations"
        },
        "identity" : {
          "href" : "https://api-test.payline.io:443/identities/IDh8cH5oknmAQ3kHaodJuwZi"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIiiJ66LJMiYretPh9tcXHXJ/transfers"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIiiJ66LJMiYretPh9tcXHXJ/verifications"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    }, {
      "id" : "PIGy4XsD7cKYBkMhmEDeMvs",
      "fingerprint" : "FPR-1645745263",
      "tags" : { },
      "name" : null,
      "created_at" : "2017-04-24T20:22:39.36Z",
      "updated_at" : "2017-04-24T20:22:39.36Z",
      "instrument_type" : "VIRTUAL",
      "type" : "VIRTUAL",
      "currency" : "USD",
      "identity" : "IDh8cH5oknmAQ3kHaodJuwZi",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIGy4XsD7cKYBkMhmEDeMvs"
        },
        "authorizations" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIGy4XsD7cKYBkMhmEDeMvs/authorizations"
        },
        "identity" : {
          "href" : "https://api-test.payline.io:443/identities/IDh8cH5oknmAQ3kHaodJuwZi"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIGy4XsD7cKYBkMhmEDeMvs/transfers"
        },
        "verifications" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIGy4XsD7cKYBkMhmEDeMvs/verifications"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io/payment_instruments?offset=0&limit=20&sort=created_at,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 11
  }
}

HTTP Request

GET https://api-test.payline.io/payment_instruments

Settlements

A Settlement is a logical construct representing a collection (i.e. batch) of Transfers that are intended to be paid out to a specific Merchant.

Create a Settlement


curl https://api-test.payline.io/identities/ID8dfS5cFQYW2Ckee7BvVR4R/settlements \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "currency": "USD", 
      "tags": {
          "Internal Daily Settlement ID": "21DFASJSAKAS"
      }
  }'


import io.payline.payments.processing.client.model.Settlement;

Settlement settlement = identity.createSettlement(
  Settlement.builder()
    .currency("USD")
    .build()
);

<?php
use Payline\Resources\Identity;
use Payline\Resources\Settlement;

$identity = Identity::retrieve('ID8dfS5cFQYW2Ckee7BvVR4R');
$settlement = new Settlement(
  array(
      "currency"=> "USD", 
      "tags"=> array(
          "Internal Daily Settlement ID"=> "21DFASJSAKAS"
      )
  ));
$settlement = $identity->createSettlement($settlement);



from payline.resources import Identity
from payline.resources import Settlement

identity = Identity.get(id="ID8dfS5cFQYW2Ckee7BvVR4R")
settlement = Settlement(**
  {
      "currency": "USD", 
      "tags": {
          "Internal Daily Settlement ID": "21DFASJSAKAS"
      }
  })
identity.create_settlement(settlement)
identity = Payline::Identity.retrieve(:id=>"ID8dfS5cFQYW2Ckee7BvVR4R")
settlement = identity.create_settlement(
  {
      "currency"=> "USD", 
      "tags"=> {
          "Internal Daily Settlement ID"=> "21DFASJSAKAS"
      }
  })

Example Response:

{
  "id" : "ST7ix1LibzhA7JvHQ7UMZgK5",
  "tags" : {
    "Internal Daily Settlement ID" : "21DFASJSAKAS"
  },
  "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "currency" : "USD",
  "created_at" : "2017-04-24T20:23:43.17Z",
  "updated_at" : "2017-04-24T20:23:43.18Z",
  "processor" : "DUMMY_V1",
  "total_amount" : 858236,
  "total_fees" : 85825,
  "total_fee" : 85825,
  "net_amount" : 772411,
  "destination" : null,
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "funding_transfers" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/funding_transfers"
    },
    "transfers" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers"
    },
    "fees" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers?type=fee"
    },
    "reversals" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers?type=reverse"
    },
    "credits" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers?type=credit"
    },
    "debits" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers?type=debit"
    }
  }
}

Each settlement is comprised of all the Transfers that have a SUCCEEDED state and that have not been previously settled out. In other words, if a merchant has a Transfer in the PENDING state it will not be included in the batch settlement. In addition, Settlements will include any refunded Transfers as a deduction. The total_amount is the net settled amount in cents (i.e. the amount in cents that will be deposited into your merchant’s bank account after your fees have been deducted).

HTTP Request

POST https://api-test.payline.io/identities/:IDENTITY_ID/settlements

URL Parameters

Parameter Description
:IDENTITY_ID ID of the Identity for the merchant you wish to settle out

Request Arguments

Field Type Description
currency integer, required 3-letter currency code that the funds should be deposited (e.g. USD)
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)

Retrieve a Settlement



curl https://api-test.payline.io/settlements/ST7ix1LibzhA7JvHQ7UMZgK5 \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \


import io.payline.payments.processing.client.model.Settlement;

Settlement settlement = client.settlementsClient().fetch("ST7ix1LibzhA7JvHQ7UMZgK5");

<?php
use Payline\Resources\Settlement;

$settlement = Settlement::retrieve('ST7ix1LibzhA7JvHQ7UMZgK5');




settlement = Payline::Settlement.retrieve(:id=>"ST7ix1LibzhA7JvHQ7UMZgK5")

Example Response:

{
  "id" : "ST7ix1LibzhA7JvHQ7UMZgK5",
  "tags" : {
    "Internal Daily Settlement ID" : "21DFASJSAKAS"
  },
  "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "currency" : "USD",
  "created_at" : "2017-04-24T20:23:43.13Z",
  "updated_at" : "2017-04-24T20:23:43.94Z",
  "processor" : "DUMMY_V1",
  "total_amount" : 858236,
  "total_fees" : 85825,
  "total_fee" : 85825,
  "net_amount" : 772411,
  "destination" : "PIhGEt5UWQXxrvNba8bc6jxg",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "funding_transfers" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/funding_transfers"
    },
    "transfers" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers"
    },
    "fees" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers?type=fee"
    },
    "reversals" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers?type=reverse"
    },
    "credits" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers?type=credit"
    },
    "debits" : {
      "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers?type=debit"
    }
  }
}

Fetch a previously created Settlement.

HTTP Request

POST https://api-test.payline.io/settlements/:SETTLEMENT_ID/

URL Parameters

Parameter Description
:SETTLEMENT_ID ID of the Settlement

List all Settlements

curl https://api-test.payline.io/settlements/ \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3

client.settlementsClient().<Resources<Settlement>>resourcesIterator()
  .forEachRemaining(settlementPage -> {
    Collection<Settlement> settlements = settlementPage.getContent();
    //do something
  });
<?php
use Payline\Resources\Settlement;

$settlements = Settlement::getPagination("/settlements");




from payline.resources import Settlement
settlements = Settlement.get()

settlements = Payline::Settlement.retrieve

Example Response:

{
  "_embedded" : {
    "settlements" : [ {
      "id" : "ST7ix1LibzhA7JvHQ7UMZgK5",
      "tags" : {
        "Internal Daily Settlement ID" : "21DFASJSAKAS"
      },
      "identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
      "currency" : "USD",
      "created_at" : "2017-04-24T20:23:43.13Z",
      "updated_at" : "2017-04-24T20:23:43.94Z",
      "processor" : "DUMMY_V1",
      "total_amount" : 858236,
      "total_fees" : 85825,
      "total_fee" : 85825,
      "net_amount" : 772411,
      "destination" : "PIhGEt5UWQXxrvNba8bc6jxg",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "identity" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
        },
        "funding_transfers" : {
          "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/funding_transfers"
        },
        "transfers" : {
          "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers"
        },
        "fees" : {
          "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers?type=fee"
        },
        "reversals" : {
          "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers?type=reverse"
        },
        "credits" : {
          "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers?type=credit"
        },
        "debits" : {
          "href" : "https://api-test.payline.io:443/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers?type=debit"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io/settlements?offset=0&limit=20&sort=created_at,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 1
  }
}

List the Transfers of type CREDIT that result from issuing funding instructions for the Settlement.

HTTP Request

GET https://api-test.payline.io/settlements/:SETTLEMENT_ID/funding_transfers

URL Parameters

Parameter Description
:SETTLEMENT_ID ID of the Settlement

List Funding Transfers

curl https://api-test.payline.io/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/funding_transfers \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3

Settlement settlement = client.settlementsClient().fetch("ST7ix1LibzhA7JvHQ7UMZgK5");
  settlement.fundingTransfersClient().<Resources<Transfer>>resourcesIterator()
    .forEachRemaining(page -> {
      Collection<Transfer> transfers = page.getContent();
      transfers.forEach(transfer ->
     // do something
      );
    });
}
<?php
use Payline\Resources\Settlement;

$settlement = Settlement::retrieve('ST7ix1LibzhA7JvHQ7UMZgK5');
$settlements = Settlement::getPagination($settlement->getHref("funding_transfers"));




settlement = Payline::Settlement.retrieve(:id=>"ST7ix1LibzhA7JvHQ7UMZgK5")
transfers = settlement.funding_transfers

Example Response:

{
  "_embedded" : {
    "transfers" : [ {
      "id" : "TRpak1tBpSJ8WSw2BJH75mjV",
      "amount" : 772411,
      "tags" : {
        "Internal Daily Settlement ID" : "21DFASJSAKAS"
      },
      "state" : "PENDING",
      "trace_id" : "2a971b85-f531-4e79-9579-20517d0cbf04",
      "currency" : "USD",
      "application" : "APoo7cFGmGBiDzRarUMDyAwB",
      "source" : "PI4NUUE6FYZ5NMDT2AQ71FRK",
      "destination" : "PIhGEt5UWQXxrvNba8bc6jxg",
      "ready_to_settle_at" : null,
      "fee" : 0,
      "statement_descriptor" : null,
      "type" : "CREDIT",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2017-04-24T20:23:43.64Z",
      "updated_at" : "2017-04-24T20:23:43.89Z",
      "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
      "_links" : {
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "self" : {
          "href" : "https://api-test.payline.io:443/transfers/TRpak1tBpSJ8WSw2BJH75mjV"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/transfers/TRpak1tBpSJ8WSw2BJH75mjV/payment_instruments"
        },
        "merchant_identity" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
        },
        "reversals" : {
          "href" : "https://api-test.payline.io:443/transfers/TRpak1tBpSJ8WSw2BJH75mjV/reversals"
        },
        "fees" : {
          "href" : "https://api-test.payline.io:443/transfers/TRpak1tBpSJ8WSw2BJH75mjV/fees"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/transfers/TRpak1tBpSJ8WSw2BJH75mjV/disputes"
        },
        "source" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI4NUUE6FYZ5NMDT2AQ71FRK"
        },
        "destination" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIhGEt5UWQXxrvNba8bc6jxg"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/funding_transfers?offset=0&limit=20&sort=created_at,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 1
  }
}

List the Transfers of type CREDIT that result from issuing funding instructions for the Settlement.

HTTP Request

GET https://api-test.payline.io/settlements/:SETTLEMENT_ID/funding_transfers

URL Parameters

Parameter Description
:SETTLEMENT_ID ID of the Settlement

List Transfers in a Settlement


curl https://api-test.payline.io/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3

Settlement settlement = client.settlementsClient().fetch("ST7ix1LibzhA7JvHQ7UMZgK5");
    settlement.transfersClient().<Resources<Transfer>>resourcesIterator()
      .forEachRemaining(page -> {
        Collection<Transfer> transfers = page.getContent();
        transfers.forEach(transfer ->
       // do something
        );
      });
  }



<?php
use Payline\Resources\Settlement;

$settlement = Settlement::retrieve('ST7ix1LibzhA7JvHQ7UMZgK5');
$settlements = Settlement::getPagination($settlement->getHref("transfers"));




settlement = Payline::Settlement.retrieve(:id=>"ST7ix1LibzhA7JvHQ7UMZgK5")
transfers = settlement.transfers

Example Response:

{
  "_embedded" : {
    "transfers" : [ {
      "id" : "TR5skamCPk6w9zwgXgTE2iSV",
      "amount" : 11,
      "tags" : { },
      "state" : "SUCCEEDED",
      "trace_id" : "4ddf29ef-1e39-4509-b3ee-617945856655",
      "currency" : "USD",
      "application" : "APoo7cFGmGBiDzRarUMDyAwB",
      "source" : "PI4NUUE6FYZ5NMDT2AQ71FRK",
      "destination" : "PImLauhzQi9mZv4T17GEY7h7",
      "ready_to_settle_at" : "2017-04-24T20:23:40.56Z",
      "fee" : 0,
      "statement_descriptor" : null,
      "type" : "FEE",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2017-04-24T20:23:42.15Z",
      "updated_at" : "2017-04-24T20:23:42.46Z",
      "merchant_identity" : "IDjFtXt19dt59nd6jyyF7VuF",
      "_links" : {
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "self" : {
          "href" : "https://api-test.payline.io:443/transfers/TR5skamCPk6w9zwgXgTE2iSV"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/transfers/TR5skamCPk6w9zwgXgTE2iSV/payment_instruments"
        },
        "merchant_identity" : {
          "href" : "https://api-test.payline.io:443/identities/IDjFtXt19dt59nd6jyyF7VuF"
        },
        "reversals" : {
          "href" : "https://api-test.payline.io:443/transfers/TR5skamCPk6w9zwgXgTE2iSV/reversals"
        },
        "fees" : {
          "href" : "https://api-test.payline.io:443/transfers/TR5skamCPk6w9zwgXgTE2iSV/fees"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/transfers/TR5skamCPk6w9zwgXgTE2iSV/disputes"
        },
        "source" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI4NUUE6FYZ5NMDT2AQ71FRK"
        },
        "destination" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PImLauhzQi9mZv4T17GEY7h7"
        }
      }
    }, {
      "id" : "TRfQqshWvP1j6JbRFBrW2VZz",
      "amount" : 22255,
      "tags" : { },
      "state" : "SUCCEEDED",
      "trace_id" : "fb4d3b54-cb1d-431b-b42d-03dcc5428d06",
      "currency" : "USD",
      "application" : "APoo7cFGmGBiDzRarUMDyAwB",
      "source" : "PI4NUUE6FYZ5NMDT2AQ71FRK",
      "destination" : "PI3gSgQKtpUVUbuRiFcWemfv",
      "ready_to_settle_at" : "2017-04-24T20:23:40.56Z",
      "fee" : 0,
      "statement_descriptor" : null,
      "type" : "FEE",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2017-04-24T20:23:41.79Z",
      "updated_at" : "2017-04-24T20:23:42.09Z",
      "merchant_identity" : "IDh8cH5oknmAQ3kHaodJuwZi",
      "_links" : {
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "self" : {
          "href" : "https://api-test.payline.io:443/transfers/TRfQqshWvP1j6JbRFBrW2VZz"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/transfers/TRfQqshWvP1j6JbRFBrW2VZz/payment_instruments"
        },
        "merchant_identity" : {
          "href" : "https://api-test.payline.io:443/identities/IDh8cH5oknmAQ3kHaodJuwZi"
        },
        "reversals" : {
          "href" : "https://api-test.payline.io:443/transfers/TRfQqshWvP1j6JbRFBrW2VZz/reversals"
        },
        "fees" : {
          "href" : "https://api-test.payline.io:443/transfers/TRfQqshWvP1j6JbRFBrW2VZz/fees"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/transfers/TRfQqshWvP1j6JbRFBrW2VZz/disputes"
        },
        "source" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI4NUUE6FYZ5NMDT2AQ71FRK"
        },
        "destination" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI3gSgQKtpUVUbuRiFcWemfv"
        }
      }
    }, {
      "id" : "TRhLPEi99jmw2EvMcfKJXLw6",
      "amount" : 11,
      "tags" : { },
      "state" : "SUCCEEDED",
      "trace_id" : "4fab9867-55b1-40fd-a4b4-b79cecfea244",
      "currency" : "USD",
      "application" : "APoo7cFGmGBiDzRarUMDyAwB",
      "source" : "PI4NUUE6FYZ5NMDT2AQ71FRK",
      "destination" : "PImLauhzQi9mZv4T17GEY7h7",
      "ready_to_settle_at" : "2017-04-24T20:23:40.56Z",
      "fee" : 0,
      "statement_descriptor" : null,
      "type" : "FEE",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2017-04-24T20:23:41.47Z",
      "updated_at" : "2017-04-24T20:23:41.77Z",
      "merchant_identity" : "IDjFtXt19dt59nd6jyyF7VuF",
      "_links" : {
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "self" : {
          "href" : "https://api-test.payline.io:443/transfers/TRhLPEi99jmw2EvMcfKJXLw6"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/transfers/TRhLPEi99jmw2EvMcfKJXLw6/payment_instruments"
        },
        "merchant_identity" : {
          "href" : "https://api-test.payline.io:443/identities/IDjFtXt19dt59nd6jyyF7VuF"
        },
        "reversals" : {
          "href" : "https://api-test.payline.io:443/transfers/TRhLPEi99jmw2EvMcfKJXLw6/reversals"
        },
        "fees" : {
          "href" : "https://api-test.payline.io:443/transfers/TRhLPEi99jmw2EvMcfKJXLw6/fees"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/transfers/TRhLPEi99jmw2EvMcfKJXLw6/disputes"
        },
        "source" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI4NUUE6FYZ5NMDT2AQ71FRK"
        },
        "destination" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PImLauhzQi9mZv4T17GEY7h7"
        }
      }
    }, {
      "id" : "TR4kU6uaVwJAf5MQpFLPpg5x",
      "amount" : 63537,
      "tags" : { },
      "state" : "SUCCEEDED",
      "trace_id" : "6ca4066e-4c59-4daf-980f-b142110e4f11",
      "currency" : "USD",
      "application" : "APoo7cFGmGBiDzRarUMDyAwB",
      "source" : "PI4NUUE6FYZ5NMDT2AQ71FRK",
      "destination" : "PI3gSgQKtpUVUbuRiFcWemfv",
      "ready_to_settle_at" : "2017-04-24T20:23:40.56Z",
      "fee" : 0,
      "statement_descriptor" : null,
      "type" : "FEE",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2017-04-24T20:23:41.09Z",
      "updated_at" : "2017-04-24T20:23:41.40Z",
      "merchant_identity" : "IDh8cH5oknmAQ3kHaodJuwZi",
      "_links" : {
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "self" : {
          "href" : "https://api-test.payline.io:443/transfers/TR4kU6uaVwJAf5MQpFLPpg5x"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/transfers/TR4kU6uaVwJAf5MQpFLPpg5x/payment_instruments"
        },
        "merchant_identity" : {
          "href" : "https://api-test.payline.io:443/identities/IDh8cH5oknmAQ3kHaodJuwZi"
        },
        "reversals" : {
          "href" : "https://api-test.payline.io:443/transfers/TR4kU6uaVwJAf5MQpFLPpg5x/reversals"
        },
        "fees" : {
          "href" : "https://api-test.payline.io:443/transfers/TR4kU6uaVwJAf5MQpFLPpg5x/fees"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/transfers/TR4kU6uaVwJAf5MQpFLPpg5x/disputes"
        },
        "source" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI4NUUE6FYZ5NMDT2AQ71FRK"
        },
        "destination" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI3gSgQKtpUVUbuRiFcWemfv"
        }
      }
    }, {
      "id" : "TRgJuVToLjtLi7QVrtJhHphg",
      "amount" : 11,
      "tags" : { },
      "state" : "SUCCEEDED",
      "trace_id" : "eea26895-912a-4f20-8124-cc8652f0a2ba",
      "currency" : "USD",
      "application" : "APoo7cFGmGBiDzRarUMDyAwB",
      "source" : "PI4NUUE6FYZ5NMDT2AQ71FRK",
      "destination" : "PImLauhzQi9mZv4T17GEY7h7",
      "ready_to_settle_at" : "2017-04-24T20:23:40.56Z",
      "fee" : 0,
      "statement_descriptor" : null,
      "type" : "FEE",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2017-04-24T20:23:40.67Z",
      "updated_at" : "2017-04-24T20:23:41.06Z",
      "merchant_identity" : "IDjFtXt19dt59nd6jyyF7VuF",
      "_links" : {
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "self" : {
          "href" : "https://api-test.payline.io:443/transfers/TRgJuVToLjtLi7QVrtJhHphg"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/transfers/TRgJuVToLjtLi7QVrtJhHphg/payment_instruments"
        },
        "merchant_identity" : {
          "href" : "https://api-test.payline.io:443/identities/IDjFtXt19dt59nd6jyyF7VuF"
        },
        "reversals" : {
          "href" : "https://api-test.payline.io:443/transfers/TRgJuVToLjtLi7QVrtJhHphg/reversals"
        },
        "fees" : {
          "href" : "https://api-test.payline.io:443/transfers/TRgJuVToLjtLi7QVrtJhHphg/fees"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/transfers/TRgJuVToLjtLi7QVrtJhHphg/disputes"
        },
        "source" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI4NUUE6FYZ5NMDT2AQ71FRK"
        },
        "destination" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PImLauhzQi9mZv4T17GEY7h7"
        }
      }
    }, {
      "id" : "TRbTkUqNB9bfmbBgL9KRFWux",
      "amount" : 100,
      "tags" : { },
      "state" : "SUCCEEDED",
      "trace_id" : "d37622b3-f96d-402a-b53f-f54b6894c3c9",
      "currency" : "USD",
      "application" : "APoo7cFGmGBiDzRarUMDyAwB",
      "source" : "PIgM6zjoU4nN7PZmGwGMMaf6",
      "destination" : "PI4NUUE6FYZ5NMDT2AQ71FRK",
      "ready_to_settle_at" : "2017-04-24T20:23:40.56Z",
      "fee" : 10,
      "statement_descriptor" : "PLD*PRESTIGE WORLD WI",
      "type" : "DEBIT",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2017-04-24T20:22:53.82Z",
      "updated_at" : "2017-04-24T20:23:01.83Z",
      "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
      "_links" : {
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "self" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbTkUqNB9bfmbBgL9KRFWux"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbTkUqNB9bfmbBgL9KRFWux/payment_instruments"
        },
        "merchant_identity" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
        },
        "reversals" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbTkUqNB9bfmbBgL9KRFWux/reversals"
        },
        "fees" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbTkUqNB9bfmbBgL9KRFWux/fees"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbTkUqNB9bfmbBgL9KRFWux/disputes"
        },
        "source" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6"
        },
        "destination" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI4NUUE6FYZ5NMDT2AQ71FRK"
        }
      }
    }, {
      "id" : "TRxhhkgK7oWzJymN1dYz4sBs",
      "amount" : 222658,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "trace_id" : "bc92f8da-7c34-41d7-adea-b5d1c93f3723",
      "currency" : "USD",
      "application" : "APoo7cFGmGBiDzRarUMDyAwB",
      "source" : "PIhXugCSbMFHDggWrvxJ6Pan",
      "destination" : "PI4NUUE6FYZ5NMDT2AQ71FRK",
      "ready_to_settle_at" : "2017-04-24T20:23:40.56Z",
      "fee" : 22266,
      "statement_descriptor" : "PLD*PRESTIGE WORLD WI",
      "type" : "DEBIT",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2017-04-24T20:22:50.25Z",
      "updated_at" : "2017-04-24T20:23:04.22Z",
      "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
      "_links" : {
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "self" : {
          "href" : "https://api-test.payline.io:443/transfers/TRxhhkgK7oWzJymN1dYz4sBs"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/transfers/TRxhhkgK7oWzJymN1dYz4sBs/payment_instruments"
        },
        "merchant_identity" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
        },
        "reversals" : {
          "href" : "https://api-test.payline.io:443/transfers/TRxhhkgK7oWzJymN1dYz4sBs/reversals"
        },
        "fees" : {
          "href" : "https://api-test.payline.io:443/transfers/TRxhhkgK7oWzJymN1dYz4sBs/fees"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/transfers/TRxhhkgK7oWzJymN1dYz4sBs/disputes"
        },
        "source" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIhXugCSbMFHDggWrvxJ6Pan"
        },
        "destination" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI4NUUE6FYZ5NMDT2AQ71FRK"
        }
      }
    }, {
      "id" : "TRbiwws9kHxMa3GfTbR4bDqM",
      "amount" : 635478,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "trace_id" : "5561bc06-3975-4729-9b7c-fc7703cceb38",
      "currency" : "USD",
      "application" : "APoo7cFGmGBiDzRarUMDyAwB",
      "source" : "PIgM6zjoU4nN7PZmGwGMMaf6",
      "destination" : "PI4NUUE6FYZ5NMDT2AQ71FRK",
      "ready_to_settle_at" : "2017-04-24T20:23:40.56Z",
      "fee" : 63548,
      "statement_descriptor" : "PLD*PRESTIGE WORLD WI",
      "type" : "DEBIT",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2017-04-24T20:22:49.47Z",
      "updated_at" : "2017-04-24T20:23:02.78Z",
      "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
      "_links" : {
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "self" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbiwws9kHxMa3GfTbR4bDqM"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbiwws9kHxMa3GfTbR4bDqM/payment_instruments"
        },
        "merchant_identity" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
        },
        "reversals" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbiwws9kHxMa3GfTbR4bDqM/reversals"
        },
        "fees" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbiwws9kHxMa3GfTbR4bDqM/fees"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbiwws9kHxMa3GfTbR4bDqM/disputes"
        },
        "source" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6"
        },
        "destination" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI4NUUE6FYZ5NMDT2AQ71FRK"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io/settlements/ST7ix1LibzhA7JvHQ7UMZgK5/transfers?offset=0&limit=20&sort=created_at,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 8
  }
}

List the batch of Transfers of type DEBIT and REFUND that comprise the net settled amount of a Settlement.

HTTP Request

GET https://api-test.payline.io/settlements/:SETTLEMENT_ID/transfers

URL Parameters

Parameter Description
:SETTLEMENT_ID ID of the Settlement

Transfers

A Transfer represents any flow of funds either to or from a Payment Instrument. For example, a Transfer can be either a debit to a card, a credit to a bank account, or a refund to a card depending on the request.

Transfers can have four possible states values: PENDING, SUCCEEDED, FAILED, or CANCELED.

By default, Transfers will be in a PENDING state and will eventually (typically within an hour) update to SUCCEEDED.

ready_to_settle_at field can have 2 possible values:

  1. null: Funds have been captured, but are not yet ready to be paid out
  2. TIMESTAMP: A UTC timestamp that specifies when the funds will be available to be payout out. Once in the past, the Transfer will be eligible for inclusion in a batch Settlement.

Debit a Bank Account (ie eCheck)

curl https://api-test.payline.io/transfers \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
  {
      "fee": 22266, 
      "source": "PIhXugCSbMFHDggWrvxJ6Pan", 
      "merchant_identity": "ID8dfS5cFQYW2Ckee7BvVR4R", 
      "tags": {
          "order_number": "21DFASJSAKAS"
      }, 
      "currency": "USD", 
      "amount": 222658
  }'



import io.payline.payments.processing.client.model.Transfer;

Map<String, String> tags = new HashMap<>();
tags.put("name", "sample-tag");

Transfer transfer = client.transfersClient().save(
    Transfer.builder()
      .merchantIdentity("ID8dfS5cFQYW2Ckee7BvVR4R")
      .source("PIgM6zjoU4nN7PZmGwGMMaf6")
      .amount(888888)
      .currency("USD")
      .tags(tags)
      .build()
);

<?php
use Payline\Resources\Transfer;

$debit = new Transfer(
  array(
      "fee"=> 63548, 
      "source"=> "PIgM6zjoU4nN7PZmGwGMMaf6", 
      "merchant_identity"=> "ID8dfS5cFQYW2Ckee7BvVR4R", 
      "tags"=> array(
          "order_number"=> "21DFASJSAKAS"
      ), 
      "currency"=> "USD", 
      "amount"=> 635478
  ));
$debit = $debit->save();



Payline::Transfer.new(
  {
      "fee"=> 22266, 
      "source"=> "PIhXugCSbMFHDggWrvxJ6Pan", 
      "merchant_identity"=> "ID8dfS5cFQYW2Ckee7BvVR4R", 
      "tags"=> {
          "order_number"=> "21DFASJSAKAS"
      }, 
      "currency"=> "USD", 
      "amount"=> 222658
  }}).save

Example Response:

{
  "id" : "TRxhhkgK7oWzJymN1dYz4sBs",
  "amount" : 222658,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "PENDING",
  "trace_id" : "bc92f8da-7c34-41d7-adea-b5d1c93f3723",
  "currency" : "USD",
  "application" : "APoo7cFGmGBiDzRarUMDyAwB",
  "source" : "PIhXugCSbMFHDggWrvxJ6Pan",
  "destination" : "PI4NUUE6FYZ5NMDT2AQ71FRK",
  "ready_to_settle_at" : null,
  "fee" : 22266,
  "statement_descriptor" : "PLD*PRESTIGE WORLD WI",
  "type" : "DEBIT",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2017-04-24T20:22:50.30Z",
  "updated_at" : "2017-04-24T20:22:50.36Z",
  "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "_links" : {
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "self" : {
      "href" : "https://api-test.payline.io:443/transfers/TRxhhkgK7oWzJymN1dYz4sBs"
    },
    "payment_instruments" : {
      "href" : "https://api-test.payline.io:443/transfers/TRxhhkgK7oWzJymN1dYz4sBs/payment_instruments"
    },
    "merchant_identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "reversals" : {
      "href" : "https://api-test.payline.io:443/transfers/TRxhhkgK7oWzJymN1dYz4sBs/reversals"
    },
    "fees" : {
      "href" : "https://api-test.payline.io:443/transfers/TRxhhkgK7oWzJymN1dYz4sBs/fees"
    },
    "disputes" : {
      "href" : "https://api-test.payline.io:443/transfers/TRxhhkgK7oWzJymN1dYz4sBs/disputes"
    },
    "source" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIhXugCSbMFHDggWrvxJ6Pan"
    },
    "destination" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PI4NUUE6FYZ5NMDT2AQ71FRK"
    }
  }
}

A Transfer representing a customer payment where funds are obtained from a bank account (i.e. ACH Debit, eCheck). These specific Transfers are distinguished by their type which return DEBIT.

HTTP Request

POST https://api-test.payline.io/transfers

Request Arguments

Field Type Description
source string, required ID of the Payment Instrument that will be debited
merchant_identity string, required Identity ID of the merchant whom you’re charging on behalf of
amount integer, required The total amount that will be debited in cents (e.g. 100 cents to debit $1.00)
fee integer, optional The amount of the Transfer you would like to collect as your fee in cents. Defaults to zero (Must be less than or equal to the amount)
currency string, required 3-letter ISO code designating the currency of the Transfers (e.g. USD)
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers)

Retrieve a Transfer


curl https://api-test.payline.io/transfers/TRbiwws9kHxMa3GfTbR4bDqM \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3



import io.payline.payments.processing.client.model.Transfer;

Transfer transfer = client.transfersClient().fetch("TRbiwws9kHxMa3GfTbR4bDqM");

<?php
use Payline\Resources\Transfer;

$transfer = Transfer::retrieve('TRbiwws9kHxMa3GfTbR4bDqM');





from payline.resources import Transfer
transfer = Transfer.get(id="TRbiwws9kHxMa3GfTbR4bDqM")

transfer = Payline::Transfer.retrieve(:id=> "TRbiwws9kHxMa3GfTbR4bDqM")

Example Response:

{
  "id" : "TRbiwws9kHxMa3GfTbR4bDqM",
  "amount" : 635478,
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "state" : "PENDING",
  "trace_id" : "5561bc06-3975-4729-9b7c-fc7703cceb38",
  "currency" : "USD",
  "application" : "APoo7cFGmGBiDzRarUMDyAwB",
  "source" : "PIgM6zjoU4nN7PZmGwGMMaf6",
  "destination" : "PI4NUUE6FYZ5NMDT2AQ71FRK",
  "ready_to_settle_at" : null,
  "fee" : 63548,
  "statement_descriptor" : "PLD*PRESTIGE WORLD WI",
  "type" : "DEBIT",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2017-04-24T20:22:49.47Z",
  "updated_at" : "2017-04-24T20:22:49.60Z",
  "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "_links" : {
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "self" : {
      "href" : "https://api-test.payline.io:443/transfers/TRbiwws9kHxMa3GfTbR4bDqM"
    },
    "payment_instruments" : {
      "href" : "https://api-test.payline.io:443/transfers/TRbiwws9kHxMa3GfTbR4bDqM/payment_instruments"
    },
    "merchant_identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "reversals" : {
      "href" : "https://api-test.payline.io:443/transfers/TRbiwws9kHxMa3GfTbR4bDqM/reversals"
    },
    "fees" : {
      "href" : "https://api-test.payline.io:443/transfers/TRbiwws9kHxMa3GfTbR4bDqM/fees"
    },
    "disputes" : {
      "href" : "https://api-test.payline.io:443/transfers/TRbiwws9kHxMa3GfTbR4bDqM/disputes"
    },
    "source" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6"
    },
    "destination" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PI4NUUE6FYZ5NMDT2AQ71FRK"
    }
  }
}

HTTP Request

GET https://api-test.payline.io/transfers/:TRANSFER_ID

URL Parameters

Parameter Description
:TRANSFER_ID ID of the Transfer

Refund a Debit


curl https://api-test.payline.io/transfers/TRbiwws9kHxMa3GfTbR4bDqM/reversals \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d  '
          {
          "refund_amount" : 100
        }
        '


import io.payline.payments.processing.client.model.Refund;

Refund refund = transfer.reverse(100L);

<?php
use Payline\Resources\Transfer;

$debit = Transfer::retrieve('TRbiwws9kHxMa3GfTbR4bDqM');
$refund = $debit->reverse(11);


from payline.resources import Transfer

transfer = Transfer.get(id="TRbiwws9kHxMa3GfTbR4bDqM")
transfer.reverse(**
          {
          "refund_amount" : 100
        }
        )
transfer = Payline::Transfer.retrieve(:id=> "TRbiwws9kHxMa3GfTbR4bDqM")

refund = transfer.reverse(100)

Example Response:

{
  "id" : "TRaViZkCAo1Xpg6x8ZCgGSMD",
  "amount" : 504041,
  "tags" : { },
  "state" : "SUCCEEDED",
  "trace_id" : "5053c0ec-e8fa-4390-90f4-ed292e7e92cf",
  "currency" : "USD",
  "application" : "APoo7cFGmGBiDzRarUMDyAwB",
  "source" : "PI4NUUE6FYZ5NMDT2AQ71FRK",
  "destination" : "PIgM6zjoU4nN7PZmGwGMMaf6",
  "ready_to_settle_at" : null,
  "fee" : 50404,
  "statement_descriptor" : "PLD*PRESTIGE WORLD WI",
  "type" : "REVERSAL",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2017-04-24T20:22:52.70Z",
  "updated_at" : "2017-04-24T20:22:52.77Z",
  "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
  "_links" : {
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    },
    "self" : {
      "href" : "https://api-test.payline.io:443/transfers/TRaViZkCAo1Xpg6x8ZCgGSMD"
    },
    "parent" : {
      "href" : "https://api-test.payline.io:443/transfers/TRsUcLA9ohipAQTRBNoFm93j"
    },
    "destination" : {
      "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6"
    },
    "merchant_identity" : {
      "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
    },
    "payment_instruments" : {
      "href" : "https://api-test.payline.io:443/transfers/TRaViZkCAo1Xpg6x8ZCgGSMD/payment_instruments"
    }
  }
}

A Transfer representing the refund (i.e. reversal) of a previously created Transfer (type DEBIT). The refunded amount may be any value up to the amount of the original Transfer. These specific Transfers are distinguished by their type which return REVERSAL.

HTTP Request

POST https://api-test.payline.io/transfers/:TRANSFER_ID/reversals

URL Parameters

Parameter Description
:TRANSFER_ID ID of the original Transfer

Request Arguments

Field Type Description
refund_amount integer, required The amount of the refund in cents (Must be equal to or less than the amount of the original Transfer)

List all Transfers

curl https://api-test.payline.io/transfers \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3

import io.payline.payments.processing.client.model.Transfer;

client.transfersClient().<Resources<Transfer>>resourcesIterator()
  .forEachRemaining(transfersPage -> {
    Collection<Transfer> transfers = transfersPage.getContent();
    //do something with `transfers`
  });

<?php
use Payline\Resources\Transfer;

$transfers = Transfer::getPagination("/transfers");




from payline.resources import Transfer
transfer = Transfer.get()

transfers = Payline::Transfer.retrieve

Example Response:

{
  "_embedded" : {
    "transfers" : [ {
      "id" : "TRbTkUqNB9bfmbBgL9KRFWux",
      "amount" : 100,
      "tags" : { },
      "state" : "SUCCEEDED",
      "trace_id" : "d37622b3-f96d-402a-b53f-f54b6894c3c9",
      "currency" : "USD",
      "application" : "APoo7cFGmGBiDzRarUMDyAwB",
      "source" : "PIgM6zjoU4nN7PZmGwGMMaf6",
      "destination" : "PI4NUUE6FYZ5NMDT2AQ71FRK",
      "ready_to_settle_at" : null,
      "fee" : 10,
      "statement_descriptor" : "PLD*PRESTIGE WORLD WI",
      "type" : "DEBIT",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2017-04-24T20:22:53.82Z",
      "updated_at" : "2017-04-24T20:23:01.83Z",
      "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
      "_links" : {
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "self" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbTkUqNB9bfmbBgL9KRFWux"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbTkUqNB9bfmbBgL9KRFWux/payment_instruments"
        },
        "merchant_identity" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
        },
        "reversals" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbTkUqNB9bfmbBgL9KRFWux/reversals"
        },
        "fees" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbTkUqNB9bfmbBgL9KRFWux/fees"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbTkUqNB9bfmbBgL9KRFWux/disputes"
        },
        "source" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6"
        },
        "destination" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI4NUUE6FYZ5NMDT2AQ71FRK"
        }
      }
    }, {
      "id" : "TRaViZkCAo1Xpg6x8ZCgGSMD",
      "amount" : 504041,
      "tags" : { },
      "state" : "SUCCEEDED",
      "trace_id" : "d7ae0c31-f95e-4b1b-8260-10a76c8f72cd",
      "currency" : "USD",
      "application" : "APoo7cFGmGBiDzRarUMDyAwB",
      "source" : "PI4NUUE6FYZ5NMDT2AQ71FRK",
      "destination" : "PIgM6zjoU4nN7PZmGwGMMaf6",
      "ready_to_settle_at" : null,
      "fee" : 50404,
      "statement_descriptor" : "PLD*PRESTIGE WORLD WI",
      "type" : "REVERSAL",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2017-04-24T20:22:52.59Z",
      "updated_at" : "2017-04-24T20:22:52.77Z",
      "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
      "_links" : {
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "self" : {
          "href" : "https://api-test.payline.io:443/transfers/TRaViZkCAo1Xpg6x8ZCgGSMD"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/transfers/TRaViZkCAo1Xpg6x8ZCgGSMD/payment_instruments"
        },
        "merchant_identity" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
        },
        "parent" : {
          "href" : "https://api-test.payline.io:443/transfers/TRsUcLA9ohipAQTRBNoFm93j"
        },
        "destination" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6"
        }
      }
    }, {
      "id" : "TRsUcLA9ohipAQTRBNoFm93j",
      "amount" : 504041,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "CANCELED",
      "trace_id" : "f8be48da-3fe1-43c7-addd-e8e7cf12ca8b",
      "currency" : "USD",
      "application" : "APoo7cFGmGBiDzRarUMDyAwB",
      "source" : "PIgM6zjoU4nN7PZmGwGMMaf6",
      "destination" : "PI4NUUE6FYZ5NMDT2AQ71FRK",
      "ready_to_settle_at" : null,
      "fee" : 50404,
      "statement_descriptor" : "PLD*PRESTIGE WORLD WI",
      "type" : "DEBIT",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2017-04-24T20:22:52.04Z",
      "updated_at" : "2017-04-24T20:22:52.66Z",
      "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
      "_links" : {
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "self" : {
          "href" : "https://api-test.payline.io:443/transfers/TRsUcLA9ohipAQTRBNoFm93j"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/transfers/TRsUcLA9ohipAQTRBNoFm93j/payment_instruments"
        },
        "merchant_identity" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
        },
        "reversals" : {
          "href" : "https://api-test.payline.io:443/transfers/TRsUcLA9ohipAQTRBNoFm93j/reversals"
        },
        "fees" : {
          "href" : "https://api-test.payline.io:443/transfers/TRsUcLA9ohipAQTRBNoFm93j/fees"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/transfers/TRsUcLA9ohipAQTRBNoFm93j/disputes"
        },
        "source" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6"
        },
        "destination" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI4NUUE6FYZ5NMDT2AQ71FRK"
        }
      }
    }, {
      "id" : "TRxhhkgK7oWzJymN1dYz4sBs",
      "amount" : 222658,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "PENDING",
      "trace_id" : "bc92f8da-7c34-41d7-adea-b5d1c93f3723",
      "currency" : "USD",
      "application" : "APoo7cFGmGBiDzRarUMDyAwB",
      "source" : "PIhXugCSbMFHDggWrvxJ6Pan",
      "destination" : "PI4NUUE6FYZ5NMDT2AQ71FRK",
      "ready_to_settle_at" : null,
      "fee" : 22266,
      "statement_descriptor" : "PLD*PRESTIGE WORLD WI",
      "type" : "DEBIT",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2017-04-24T20:22:50.25Z",
      "updated_at" : "2017-04-24T20:22:50.36Z",
      "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
      "_links" : {
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "self" : {
          "href" : "https://api-test.payline.io:443/transfers/TRxhhkgK7oWzJymN1dYz4sBs"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/transfers/TRxhhkgK7oWzJymN1dYz4sBs/payment_instruments"
        },
        "merchant_identity" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
        },
        "reversals" : {
          "href" : "https://api-test.payline.io:443/transfers/TRxhhkgK7oWzJymN1dYz4sBs/reversals"
        },
        "fees" : {
          "href" : "https://api-test.payline.io:443/transfers/TRxhhkgK7oWzJymN1dYz4sBs/fees"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/transfers/TRxhhkgK7oWzJymN1dYz4sBs/disputes"
        },
        "source" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIhXugCSbMFHDggWrvxJ6Pan"
        },
        "destination" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI4NUUE6FYZ5NMDT2AQ71FRK"
        }
      }
    }, {
      "id" : "TRbiwws9kHxMa3GfTbR4bDqM",
      "amount" : 635478,
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "state" : "SUCCEEDED",
      "trace_id" : "5561bc06-3975-4729-9b7c-fc7703cceb38",
      "currency" : "USD",
      "application" : "APoo7cFGmGBiDzRarUMDyAwB",
      "source" : "PIgM6zjoU4nN7PZmGwGMMaf6",
      "destination" : "PI4NUUE6FYZ5NMDT2AQ71FRK",
      "ready_to_settle_at" : null,
      "fee" : 63548,
      "statement_descriptor" : "PLD*PRESTIGE WORLD WI",
      "type" : "DEBIT",
      "messages" : [ ],
      "raw" : null,
      "created_at" : "2017-04-24T20:22:49.47Z",
      "updated_at" : "2017-04-24T20:23:02.78Z",
      "merchant_identity" : "ID8dfS5cFQYW2Ckee7BvVR4R",
      "_links" : {
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        },
        "self" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbiwws9kHxMa3GfTbR4bDqM"
        },
        "payment_instruments" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbiwws9kHxMa3GfTbR4bDqM/payment_instruments"
        },
        "merchant_identity" : {
          "href" : "https://api-test.payline.io:443/identities/ID8dfS5cFQYW2Ckee7BvVR4R"
        },
        "reversals" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbiwws9kHxMa3GfTbR4bDqM/reversals"
        },
        "fees" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbiwws9kHxMa3GfTbR4bDqM/fees"
        },
        "disputes" : {
          "href" : "https://api-test.payline.io:443/transfers/TRbiwws9kHxMa3GfTbR4bDqM/disputes"
        },
        "source" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PIgM6zjoU4nN7PZmGwGMMaf6"
        },
        "destination" : {
          "href" : "https://api-test.payline.io:443/payment_instruments/PI4NUUE6FYZ5NMDT2AQ71FRK"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io/transfers?offset=0&limit=20&sort=created_at,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 5
  }
}

HTTP Request

GET https://api-test.payline.io/transfers

Webhooks

Webhooks allow you to build or set up integrations which subscribe to certain automated notifications (i.e. events) on the Payline API. When one of those events is triggered, we’ll send a HTTP POST payload to the webhook’s configured URL. Instead of forcing you to pull info from the API, webhooks push notifications to your configured URL endpoint. Webhooks are particularly useful for updating asynchronous state changes in Transfers, Merchant account provisioning, and listening for notifications of newly created Disputes.

Create a Webhook


curl https://api-test.payline.io/webhooks \
    -H "Content-Type: application/vnd.json+api" \
    -u US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3 \
    -d '
                    {
                    "url" : "https://fayswfq2mtui.runscope.net"
                    }
                '


import io.payline.payments.processing.client.model.Webhook;

Webhook webhook = client.webhookClient().save(
    Webhook.builder()
      .url("https://tools.ietf.org/html/rfc2606#section-3")
      .build()
);


<?php
use Payline\Resources\Webhook;

$webhook = new Webhook(
                    array(
                    "url" => "https=>//fayswfq2mtui.runscope.net"
                    )
                );
$webhook = $webhook->save();



from payline.resources import Webhook
webhook = Webhook(**
                    {
                    "url" : "https://fayswfq2mtui.runscope.net"
                    }
                ).save()

webhook = Payline::Webhook.new(
                    {
                    "url" => "https=>//fayswfq2mtui.runscope.net"
                    }
                ).save

Example Response:

{
  "id" : "WHvcb2445sB1VgNk1wEnxRPU",
  "url" : "https://fayswfq2mtui.runscope.net",
  "enabled" : true,
  "application" : "APoo7cFGmGBiDzRarUMDyAwB",
  "created_at" : "2017-04-24T20:22:41.41Z",
  "updated_at" : "2017-04-24T20:22:41.41Z",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/webhooks/WHvcb2445sB1VgNk1wEnxRPU"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    }
  }
}

HTTP Request

POST https://api-test.payline.io/webhooks

Request Arguments

Field Type Description
url string, required The HTTP or HTTPS url where the callbacks will be sent via POST request (max 120 characters)

Retrieve a Webhook




curl https://api-test.payline.io/webhooks/WHvcb2445sB1VgNk1wEnxRPU \
    -H "Content-Type: application/vnd.json+api" \
    -u US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3



import io.payline.payments.processing.client.model.Webhook;

Webhook webhook = client.webhookClient().fetch("WHvcb2445sB1VgNk1wEnxRPU");

<?php
use Payline\Resources\Webhook;

$webhook = Webhook::retrieve('WHvcb2445sB1VgNk1wEnxRPU');





from payline.resources import Webhook
webhook = Webhook.get(id="WHvcb2445sB1VgNk1wEnxRPU")

webhook = Payline::Webhook.retrieve(:id=> "WHvcb2445sB1VgNk1wEnxRPU")


Example Response:

{
  "id" : "WHvcb2445sB1VgNk1wEnxRPU",
  "url" : "https://fayswfq2mtui.runscope.net",
  "enabled" : true,
  "application" : "APoo7cFGmGBiDzRarUMDyAwB",
  "created_at" : "2017-04-24T20:22:41.41Z",
  "updated_at" : "2017-04-24T20:22:41.41Z",
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io:443/webhooks/WHvcb2445sB1VgNk1wEnxRPU"
    },
    "application" : {
      "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
    }
  }
}

HTTP Request

GET https://api-test.payline.io/webhooks/:WEBHOOK_ID

URL Parameters

Parameter Description
:WEBHOOK_ID ID of the Webhook

List all Webhooks

curl https://api-test.payline.io/webhooks/ \
    -H "Content-Type: application/vnd.json+api" \
    -u  US7gYxecvqqmmk3Qyu94YAwk:2ddb1f42-dc9c-413d-a465-4c7b66ff1ef3

import io.payline.payments.processing.client.model.Webhook;

client.webhookClient().<Resources<Webhook>>resourcesIterator()
  .forEachRemaining(webhookPage -> {
    Collection<Webhook> webhooks = webhookPage.getContent();
    //do something with `webhooks`
  });
<?php
use Payline\Resources\Webhook;

$webhooks = Webhook::getPagination("/webhooks");




from payline.resources import Webhook
webhooks = Webhook.get()

webhooks = Payline::Webhook.retrieve

Example Response:

{
  "_embedded" : {
    "webhooks" : [ {
      "id" : "WHvcb2445sB1VgNk1wEnxRPU",
      "url" : "https://fayswfq2mtui.runscope.net",
      "enabled" : true,
      "application" : "APoo7cFGmGBiDzRarUMDyAwB",
      "created_at" : "2017-04-24T20:22:41.41Z",
      "updated_at" : "2017-04-24T20:22:41.41Z",
      "_links" : {
        "self" : {
          "href" : "https://api-test.payline.io:443/webhooks/WHvcb2445sB1VgNk1wEnxRPU"
        },
        "application" : {
          "href" : "https://api-test.payline.io:443/applications/APoo7cFGmGBiDzRarUMDyAwB"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-test.payline.io/webhooks?offset=0&limit=20&sort=created_at,desc"
    }
  },
  "page" : {
    "offset" : 0,
    "limit" : 20,
    "count" : 1
  }
}

HTTP Request

GET https://api-test.payline.io/webhooks

Sample Payloads

<?php


Created Identity

{
  "type" : "created",
  "entity" : "identity",
  "occurred_at" : "2017-04-24T17:59:49.330",
  "_embedded" : {
    "identitys" : [ {
      "updated_at" : "2017-04-24T17:59:49.29Z",
      "created_at" : "2017-04-24T17:59:49.29Z",
      "id" : "IDmQXwGjkUpymXoX8doL4nha",
      "entity" : {
        "title" : "CEO",
        "first_name" : "dwayne",
        "last_name" : "Sunkhronos",
        "email" : "user@example.org",
        "business_name" : "ACME Anchors",
        "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
        "doing_business_as" : "ACME Anchors",
        "phone" : "1234567890",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 7",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "max_transaction_amount" : 12000000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.ACMEAnchors.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PRIVATE",
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "ACME Anchors"
      },
      "tags" : {
        "Studio Rating" : "4.7"
      }
    } ]
  }
}

Updated Identity

{
  "type" : "updated",
  "entity" : "identity",
  "occurred_at" : "2017-04-24T18:00:14.397",
  "_embedded" : {
    "identitys" : [ {
      "updated_at" : "2017-04-24T18:00:14.35Z",
      "created_at" : "2017-04-24T17:59:49.27Z",
      "id" : "IDmQXwGjkUpymXoX8doL4nha",
      "entity" : {
        "title" : "CTO",
        "first_name" : "Bernard",
        "last_name" : "Lopez",
        "email" : "user@example.org",
        "business_name" : "Bobs Burgers",
        "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
        "doing_business_as" : "Bobs Burgers",
        "phone" : "7144177878",
        "business_phone" : "+1 (408) 756-4497",
        "personal_address" : {
          "line1" : "712 Douglass St",
          "line2" : "Apartment 2",
          "city" : "San Diego",
          "region" : "CA",
          "postal_code" : "94194",
          "country" : "USA"
        },
        "business_address" : {
          "line1" : "741 Douglass St",
          "line2" : "Apartment 8",
          "city" : "San Mateo",
          "region" : "CA",
          "postal_code" : "94114",
          "country" : "USA"
        },
        "mcc" : "0742",
        "dob" : {
          "day" : 2,
          "month" : 5,
          "year" : 1988
        },
        "max_transaction_amount" : 1200000,
        "amex_mid" : null,
        "discover_mid" : null,
        "url" : "www.BobsBurgers.com",
        "annual_card_volume" : 12000000,
        "has_accepted_credit_cards_previously" : true,
        "incorporation_date" : {
          "day" : 27,
          "month" : 6,
          "year" : 1978
        },
        "principal_percentage_ownership" : 50,
        "short_business_name" : null,
        "ownership_type" : "PRIVATE",
        "tax_id_provided" : true,
        "business_tax_id_provided" : true,
        "default_statement_descriptor" : "Bobs Burgers"
      },
      "tags" : {
        "key" : "value_2"
      }
    } ]
  }
}

Provision a Merchant

{
  "type" : "created",
  "entity" : "merchant",
  "occurred_at" : "2017-04-24T20:07:31.335",
  "_embedded" : {
    "merchants" : [ {
      "updated_at" : "2017-04-24T20:07:31.16Z",
      "identity" : "IDt7RmWJh2XBg8XoYAPjpRh5",
      "settlement_enabled" : true,
      "created_at" : "2017-04-24T20:07:31.07Z",
      "id" : "MUoKXSZYCx735KT6W5a6bqFD",
      "processing_enabled" : true,
      "onboarding_state" : "APPROVED",
      "processor" : "DUMMY_V1",
      "verification" : null,
      "merchant_profile" : "MP8Haoew6mPrL4rJaoDiCQXJ",
      "tags" : { }
    } ]
  }
}

Successfully Underwritten Merchant

{
  "type" : "underwritten",
  "entity" : "merchant",
  "occurred_at" : "2017-04-24T18:01:01.387",
  "_embedded" : {
    "merchants" : [ {
      "updated_at" : "2017-04-24T17:59:54.45Z",
      "identity" : "IDmQXwGjkUpymXoX8doL4nha",
      "settlement_enabled" : true,
      "created_at" : "2017-04-24T17:59:54.28Z",
      "id" : "MUv9V7TZeNebvKFSMLCbBeoi",
      "processing_enabled" : true,
      "onboarding_state" : "APPROVED",
      "processor" : "DUMMY_V1",
      "verification" : null,
      "merchant_profile" : "MPhrGii168h7KC6dkx1iVbwq",
      "tags" : { }
    } ]
  }
}

Update Merchant Processing Ability

{
  "type" : "updated",
  "entity" : "merchant",
  "occurred_at" : "2017-04-24T18:01:57.141",
  "_embedded" : {
    "merchants" : [ {
      "updated_at" : "2017-04-24T18:01:57.11Z",
      "identity" : "IDmQXwGjkUpymXoX8doL4nha",
      "settlement_enabled" : true,
      "created_at" : "2017-04-24T17:59:54.28Z",
      "id" : "MUv9V7TZeNebvKFSMLCbBeoi",
      "processing_enabled" : false,
      "onboarding_state" : "APPROVED",
      "processor" : "DUMMY_V1",
      "verification" : null,
      "merchant_profile" : "MPhrGii168h7KC6dkx1iVbwq",
      "tags" : { }
    } ]
  }
}

Created Authorization


{
  "type" : "created",
  "entity" : "authorization",
  "occurred_at" : "2016-07-06T08:15:21.734",
  "_embedded" : {
    "authorizations" : [ {
      "amount" : 100,
      "trace_id" : "5e157d2f-1362-4ab2-86af-3f97a8f28f0d",
      "created_at" : "2016-07-06T08:15:21.63Z",
      "source" : "PIeAkgVK9TPBnmyf6CSskv5i",
      "merchant_identity" : "IDradKrsCKMYJyj3VFKimKuy",
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "transfer" : null,
      "expires_at" : "2016-07-13T08:15:21.63Z",
      "updated_at" : "2016-07-06T08:15:21.65Z",
      "is_void" : false,
      "currency" : "USD",
      "id" : "AUfU8FU7RfgTmhfRagrF1RpS",
      "state" : "SUCCEEDED"
    } ]
  }
}

Created New Transfer

{
  "type" : "created",
  "entity" : "transfer",
  "occurred_at" : "2017-04-24T17:59:56.743",
  "_embedded" : {
    "transfers" : [ {
      "amount" : 847413,
      "trace_id" : "f6ff0834-a493-44a5-b732-5c9a480a8c42",
      "fee" : 84741,
      "destination" : "PIrjBc5GBbwMkG92xFHkprXo",
      "raw" : null,
      "created_at" : "2017-04-24T17:59:56.58Z",
      "source" : "PIruCXFpT6So6jRBdPHhCZrV",
      "merchant_identity" : "IDmQXwGjkUpymXoX8doL4nha",
      "type" : "DEBIT",
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      },
      "statement_descriptor" : "PLD*ACME ANCHORS",
      "ready_to_settle_at" : null,
      "application" : "APgAu3VMV4aRjfzLMn1DBe94",
      "updated_at" : "2017-04-24T17:59:56.69Z",
      "messages" : [ ],
      "currency" : "USD",
      "id" : "TRn1exHT3HdNAUNr8F4UEX9s",
      "state" : "PENDING"
    } ]
  }
}

Created New Transfer (Refund)

{
 "type" : "created",
  "entity" : "transfer",
  "occurred_at" : "2016-07-06T07:41:38.466",
  "_embedded" : {
    "transfers" : [ {
      "amount" : 100,
      "trace_id" : "e87b8ebc-177e-4e11-9cc3-6cfcfae7adc8",
      "fee" : 0,
      "destination" : "PIg3pCsoqrygp1gCvBNvfT3x",
      "created_at" : "2016-07-06T07:41:38.24Z",
      "source" : "PI2f1E5JVeQriDMeDpULnae3",
      "merchant_identity" : "IDoXe9ce6ztf6Pbpoq2WbeMt",
      "type" : "REVERSAL",
      "tags" : { },
      "statement_descriptor" : "PLD*POLLOS HERMANOS",
      "application" : "APdHz4LE8cNmJbbK7WW2egcg",
      "updated_at" : "2016-07-06T07:41:38.37Z",
      "currency" : "USD",
      "id" : "TRjgpj7b7xZXN18XyD7G3JER",
      "state" : "PENDING"
    } ]
  }
}

Updated Transfer

{
  "type" : "updated",
  "entity" : "transfer",
  "occurred_at" : "2017-04-24T18:01:52.347",
  "_embedded" : {
    "transfers" : [ {
      "amount" : 15970,
      "trace_id" : "f41b1ef3-c9f0-4f23-8cd3-30c7c5d14906",
      "fee" : 0,
      "destination" : "PIf9STwEiQHLHqMB13eMj4o",
      "raw" : null,
      "created_at" : "2017-04-24T18:01:51.16Z",
      "source" : "PIrjBc5GBbwMkG92xFHkprXo",
      "merchant_identity" : "IDidTEKbcK2PJmh1ikVQenv4",
      "type" : "FEE",
      "tags" : { },
      "statement_descriptor" : null,
      "ready_to_settle_at" : null,
      "application" : "APgAu3VMV4aRjfzLMn1DBe94",
      "updated_at" : "2017-04-24T18:01:51.39Z",
      "messages" : [ ],
      "currency" : "USD",
      "id" : "TRw9iShFJnnTfqWovqo8BHR1",
      "state" : "SUCCEEDED"
    } ]
  }
}

Create Settlement

{
  "type" : "created",
  "entity" : "settlement",
  "occurred_at" : "2017-04-24T18:01:52.974",
  "_embedded" : {
    "settlements" : [ {
      "updated_at" : "2017-04-24T18:01:52.95Z",
      "total_amount" : 1007324,
      "identity" : "IDmQXwGjkUpymXoX8doL4nha",
      "total_fees" : 100733,
      "total_fee" : 100733,
      "destination" : null,
      "created_at" : "2017-04-24T18:01:52.92Z",
      "currency" : "USD",
      "id" : "ST86ggUUqDEBgMAoxL9esysM",
      "net_amount" : 906591,
      "processor" : "DUMMY_V1",
      "tags" : {
        "Internal Daily Settlement ID" : "21DFASJSAKAS"
      }
    } ]
  }
}

Created Payment Instrument (PAYMENT_CARD)

{
  "type" : "created",
  "entity" : "instrument",
  "occurred_at" : "2016-07-06T07:06:04.751",
  "_embedded" : {
    "instruments" : [ {
      "updated_at" : "2016-07-06T07:06:04.63Z",
      "identity" : "IDbtqHvNT1eJHi3WbkbzAb5y",
      "fingerprint" : "FPR369385117",
      "created_at" : "2016-07-06T07:06:04.63Z",
      "id" : "PIx7rQE9dzEGoccQ76D22xuZ",
      "instrument_type" : "PAYMENT_CARD",
      "tags" : { }
    } ]
  }
}

Created Payment Instrument (BANK_ACCOUNT)

{
  "type" : "created",
  "entity" : "instrument",
  "occurred_at" : "2017-04-24T17:59:53.155",
  "_embedded" : {
    "instruments" : [ {
      "updated_at" : "2017-04-24T17:59:53.11Z",
      "identity" : "IDmQXwGjkUpymXoX8doL4nha",
      "fingerprint" : "FPR-1215770130",
      "created_at" : "2017-04-24T17:59:53.11Z",
      "currency" : "USD",
      "id" : "PInu8i8BBZxHSYM2t9brkogE",
      "instrument_type" : "BANK_ACCOUNT",
      "type" : "BANK_ACCOUNT",
      "tags" : {
        "Bank Account" : "Company Account"
      }
    } ]
  }
}
}

Request for Account Updater

{
  "type" : "created",
  "entity" : "instrument_update",
  "occurred_at" : "2017-04-24T18:00:05.451",
  "_embedded" : {
    "instrument_updates" : [ {
      "trace_id" : "406024cf-0a80-46e5-bbf5-433bfc01a020",
      "application" : "APgAu3VMV4aRjfzLMn1DBe94",
      "updated_at" : "2017-04-24T18:00:05.41Z",
      "payment_instrument" : "PIruCXFpT6So6jRBdPHhCZrV",
      "merchant" : "MUv9V7TZeNebvKFSMLCbBeoi",
      "messages" : [ ],
      "created_at" : "2017-04-24T18:00:05.39Z",
      "id" : "IUf2FHQSnFsxTqqQmbhS9k48",
      "state" : "PENDING"
    } ]
  }
}

Account Updater Status Update

{
  "type" : "updated",
  "entity" : "instrument_update",
  "occurred_at" : "2017-04-24T18:01:02.729",
  "_embedded" : {
    "instrument_updates" : [ {
      "trace_id" : "406024cf-0a80-46e5-bbf5-433bfc01a020",
      "application" : "APgAu3VMV4aRjfzLMn1DBe94",
      "updated_at" : "2017-04-24T18:01:02.67Z",
      "payment_instrument" : "PIruCXFpT6So6jRBdPHhCZrV",
      "merchant" : "MUv9V7TZeNebvKFSMLCbBeoi",
      "messages" : [ ],
      "created_at" : "2017-04-24T18:00:05.34Z",
      "id" : "IUf2FHQSnFsxTqqQmbhS9k48",
      "state" : "SUCCEEDED"
    } ]
  }
}

Created Dispute

{
  "type" : "created",
  "entity" : "dispute",
  "occurred_at" : "2016-07-06T08:14:01.288",
  "_embedded" : {
    "disputes" : [ {
      "occurred_at" : "2016-07-06T08:13:47.56Z",
      "reason" : "FRAUD",
      "amount" : 0,
      "transfer" : "TRnEarDDVuVkBJLBL6PhZTLT",
      "updated_at" : "2016-07-06T08:14:01.18Z",
      "identity" : "ID4DFq8Q2V1zHoaU8WCTzpge",
      "created_at" : "2016-07-06T08:14:01.18Z",
      "id" : "DIvHQsw2tcwUhkMtzXVbksxo",
      "state" : "PENDING",
      "respond_by" : "2016-07-13T08:14:01.18Z",
      "tags" : {
        "order_number" : "21DFASJSAKAS"
      }
    } ]
  }
}

Update Application Processing Ability

{
  "type" : "updated",
  "entity" : "application",
  "occurred_at" : "2017-04-24T18:01:58.011",
  "_embedded" : {
    "applications" : [ {
      "owner" : "IDidTEKbcK2PJmh1ikVQenv4",
      "updated_at" : "2017-04-24T18:01:57.98Z",
      "settlement_enabled" : true,
      "created_at" : "2017-04-24T17:59:45.73Z",
      "id" : "APgAu3VMV4aRjfzLMn1DBe94",
      "processing_enabled" : false,
      "enabled" : true,
      "tags" : {
        "application_name" : "My Application"
      }
    } ]
  }
}

Errors

Error Code Meaning
400 Bad Request – You’ve attemped an invalid request
401 Unauthorized – You have used the incorrect API key
402 Upstream Processor Error – Errors caused by 3rd party service
404 Not Found – The specified resource could not be found
422 Unprocessable Entity – The parameters were valid but the request failed. The error is usually some misunderstanding of various steps that have to be executed in order (e.g. attempting to initiate a transfer on behalf of a merchant that has not yet been approved)
500 Internal Server Error – We had a problem with our server. Try again later.