Los Angeles, CA
(650) 549-4357
Get Started
 

PaidYET Gateway REST API

The base url for the production api is: https://api.paidyet.com/v3/

The base url for the sandbox api is: https://api.sandbox-paidyet.com/v3/

The current version of the API is 3 which is denoted in the URL as “v3”. When a new API version becomes available the URL will reflect that version after the “V”. Our API is rate limited at 75 calls per minute or 7000 per day to protect against attacks. To get further information on our rate limits or to discuss increasing these limits for your project please contact support@paidyet.com.

All API endpoints return an ApiResponse object as their content. The payload section of the ApiResponse will contain the different data type objects or arrays returned from the call.

Sandbox API information here.

The spec for version 2 can be found here.

Some PaidYET API calls have the potential to return very large data sets. All endpoints that return multiple objects in the payload use a standard pagination list format. The format that is used is:

API Pagination query parameters

To retrieve large data sets we pass in the starting page and the number of results to add to each page. For example: if a dataset has 600 results you can pass in /transactions?page=3&per_page=100 to get the 300-400 results. 

 

Parameter Description
page The page offset to start querying.
per_page The number of objects per each page

APIResponse

property type description
type string The type of data being returned in the payload
items array Array of items matching the type. For instance – Transaction objects.
count int The total number of items that could have been returned matching the request criteria
pages int The total number of pages
page int The number of the page of items returned
per_page int The number of items per page of this payload

Authentication ENDPOINT

Login – [base_url]/login

PaidYET’s REST API uses bearer tokens to authenticate each API call. To obtain your bearer token for use in the API call simply pass in the subdomian and key to the login endpoint.

 

method request content payload content description
POST Authentication Bearer token object Authenticate with your PaidYET key and subdomain to retrieve a bearer token. The bearer token will expire periodically and you will need to obtain a new one. 

Example Login Request

{
	subdomain: 'xyz'
	key: '12345798abcdefg'
}

Example Login Response

{
	status: "OK"
	result: {
		"status": "success",
		"message": "login successful",
		"token": "1sd24rsdf2wsdfsq"
		"exp": 1648503842
	}
}

Card ENDPOINTS

LIST Cards on file – [base_url]/card

Credit card numbers are never visible after the initial tokenization. This endpoint will list all the tokens associated with customers on file in a merchant’s customer database. 

method request content payload content description
GET NA CreditCard Retrieve all cards that are stored on file for your PaidYET customers. These are only the cards that are saved in a customer profile. 

Tokenize Card – [base_url]/card

Tokenization is the process of breaking a stream of text/numbers up into words, phrases, symbols, or other meaningful elements called tokens. This token can then be used in place of a credit card number when processing a transaction. This is useful when a developer does not want to under take the security requirements of storing card data.

This command validates the card data and then returns a card reference token. The card reference token can be used in the card number field in most scenarios. Tokens only store the card number and the expiration date. Tokens are not related to a specific merchant and can be used across multiple merchants.

method request content payload content description
POST CreditCard CreditCard Add and tokenize a new card. Credit card numbers will not be retrievable after initial tokenization. 

Credit cards can be tokenized by filling in the following required fields. 

property required description
number yes

Full credit card number to tokenize.
exp yes

Expiration date of the credit card in the format “MM/YY”.

Get Card By Token – [base_url]/card/external-:external_ID

method request content payload content description
GET NA CreditCard Get a card using its externalID. For example doing an HTTP get call to [base_url]/card/external-abc will retrieve a card using the user defined externalID of “abc”

When tokenizing a credit card it is possible to add an externalId. This Id can be any alphanumeric string. Credit cards can then be looked up based on the externalId that was set during creation. Simply Prepend the externalId with “external-“.

Get Card By External ID – [base_url]/card/:token

method request content payload content description
GET NA CreditCard Get a card using its token. For example doing an HTTP get call to [base_url]/card/abc will retrieve a card using the token “abc”

Customer ENDPOINTS

List Customers – [base_url]/customer

method request content payload content description
GET NA Customer List the customers that are in your PaidYET account.

Add Customer – [base_url]/customer

method request content payload content description
POST Customer Customer Create a new customer

Get Customer – [base_url]/customer/:id

method request content payload content description
GET NA Customer Get a customer from their ID

Get Customer – [base_url]/customer/external-:external_id

method request content payload content description
GET NA Customer Get a customer from their custom defined externalID

When creating a customer it is possible to add an externalId. This Id can be any alphanumeric string. Customers can then be looked up based on the externalId that was set during creation. Simply Prepend the externalId with “external-“.

Update Customer – [base_url]/customer/:id

method request content payload content description
PUT Customer Customer Update a customer

List Customer Transactions – [base_url]/customer/:id/transaction

method request content payload content description
GET NA Transaction Get a collection of transactions for the customer

Search Customer – [base_url]/customer/search

method request content payload content description
GET NA Customer

Get a collection of customers matching the supplied criteria

Specify the search in the URL query string.
Example: GET [base_url]customer/search?name=John will get all customers in your database that start with John. All searches are case insensitive. If you have a custom field set for a customer, those fields are searchable by keys as well.
Query Key Description Example
first_name if there are spaces they should be url encoded first_name=john
last_name if there are spaces they should be url encoded last_name=doe
company_name if there are spaces they should be url encoded company_name=Acme Anvils
custom_fields any custom field saved to a customer can be searched shoesize=9
email url encoded email email=john@paidyet.com

POS Device ENDPOINTS

To use a POS device terminal with the API you must first register it with your account. Follow the directions on the terminal to sync the POS device with your account. Once this is done you will receive a device key. This can be used to send transactions to the POS device from the API. PaidYET supports all android based PAX terminals.

 

Cancel Device Transaction – [base_url]/device/:devicekey/transaction/:transactionkey

method request content payload content description
PUT, PATCH DeviceTransaction DeviceTransaction Cancel a transaction request on the POS device. 

Send Device Transaction – [base_url]/device/:devicekey/transaction

method request content payload content description
POST DeviceTransaction DeviceTransaction Sends a transaction to the POS device  (sale or auth). The payment will be performed on the device and return the results.

GET Device Transaction – [base_url]/device/:deviceId/transaction/:transactionkey

method request content payload content description
GET NA DeviceTransaction Gets a transaction previously sent to the POS device.

Example sale transaction

{
	amount: 1234.56
	type: 'sale'
}

Example cancel transaction

{
	type: 'cancel'
}

Transaction ENDPOINTS

This section will show you how to perform credit card transaction. Credit cards can be processed as a full sale type or as an auth only transaction. If the type field of a Transaction is left blank, the type will default to sale.

Auth Only:  Auth only transactions will need to be captured before funds can be transferred. These transactions are not placed in a batch, and will not settle until they are captured. Processing a credit/debit card authorization uses the auth transaction type. An example of this transaction type is shown here. It will run an authorization check on a customer’s credit card or checking account without actually charging the customer’s account.

 

Sale: Sale transactions are the equivalent of doing an Auth Only and then capturing it. These transactions are immediately placed into the batch and will settle at your next batch closing.  An example of this transaction can be shown here.

Process Transaction – [base_url]/transaction

method request content payload content description
POST Transaction Transaction Create a new transaction (sale or auth). Transactions can also be scheduled using this endpoint by simply passing in a schedue object.

Search Transactions – [base_url]/transaction/search

m time 

method request content payload content description
GET NA Transaction

Get a collection of transactions matching the supplied criteria

Specify the search in the URL query string. Possible query keys are below Example: GET [base_url]transaction/search?date=2022-03-22&amount=1.02 will get all transactions run on the 22nd of march 2022 for $1.02.
Query Key Description Example
date formatted as yyyy-mm-dd date=2022-03-31
datetime_start formatted as yyyy-mm-dd. Can not be used in conjunction with date query key. Must be used with date_end query key. date=2022-03-29 14:32:45
datetime_end formatted as yyyy-mm-dd hh:m:ss. Can not be used in conjunction with date query key. Must be used with start_end query key. date=2022-03-31 14:32:45
amount decimal with no currency symbol amount=1234.56
first_name if there are spaces they should be url encoded first_name=john
last_name if there are spaces they should be url encoded last_name=doe
custom_fields any custom field sent in with a transaction can be searched product=milk
status either  approved, declined or scheduled status=declined
type sale, auth, refund, void (comma seperate for multiple) type=sale,refund

Get Transaction – [base_url]/transaction/:id

Retrieves the details of a transaction that has been attempted previously. 

method request content payload content description
GET NA Transaction Get a single transaction by its ID

Refund Transaction – [base_url]/transaction/:id

A refund should be used once the transaction you are refunding has settled. If you are trying to cancel a transaction that is still in the currently open batch, you should use the void command instead.

To refund a transaction that has been settled, you will pass in the transaction object with the type of “refund”, the original transaction id, and the amount you would like to refund. Most merchant accounts do not allow you to refund more than the original amount of the transaction. However, depending on the Credit Policy, a refund can be processed for larger than the original transaction amount.

 

method request content payload content description
POST Transaction Transaction To refund a transaction that has been settled, you will pass in the transaction object with the type of “refund” and the amount you would like to refund. Most merchant accounts do not allow you to refund more than the original amount of the transaction. 

Example Refund

{
	amount: 1234.56
	type: 'refund'
}

Capture Transaction – [base_url]/transaction/:id

The capture command moves an authorized transaction into the current batch for settlement. It is possible to capture an amount other than the one originally authorized, however, you must follow the guidelines established by the merchant service bank. Capturing a higher or lower dollar amount could result in additional penalties and fees.

Most banks typically allow no more than 10 days to pass between the authorization/capture and settlement of a transaction.

method request content payload content description
PUT TransactionCapture Transaction Capture an auth only transaction.

Example Capture

{
	amount: 1234.56
	type: 'capture'
}

Void Transaction – [base_url]/transaction/:id

Once a transaction has been voided, it will not show up on the customer’s credit card statement. Customers who have online banking that allows them to see “Pending” transactions may see the voided transaction for a few days before it disappears.

You can only void a transaction that hasn’t been settled yet. A transaction is settled when the batch that it is in has been closed. If the transaction has been settled, you must run a refund instead using a void transaction. If you run a credit, both the credit and the initial charge will show up on the customer’s credit card statement.

You can void a transaction by sending in the original transaction id with a type of “void”.

 

method request content payload content description
PATCH Transaction Type Transaction Void a transaction

Example Void

{
	type: 'void'
}

Examples

In the below example a credit card is being scheduled to be processed as a sale transaction at a later date. This transaction will automatically process on the schedule date. A sale transaction will be processed every month on the 11th for $1,234.56 until 11 payments have been made. The customer for this transaction will also be stored in this merchants customer database. 

Scheduled Sale Transaction with custom fields

{
	amount: 1234.56
	credit_card: {
		number: '4111111111111111',
		exp: '04/29'
		name: 'John Doe',
		cvv: 111
	},
	type: 'sale',
	billing_address: {
                addresss: '111 1st ave n',
                city: 'New York City',
                state: "NY",
                postal: 50001
  	},
	custom_fields:[
	{
		key: 'sku',
		value: '123456789',
	},
        {
          key: 'color',
          value: 'blue'
        }
	],
	schedule:{
		date: '2025-09-11 11:45:00'
		repeat:{
			period: 'monthly', 
			interval: 1 
		},
		repeatcancel: {
			type: 'count', 
			value:  11
		}
	},
	customer: {
		first_name: 'John',
		last_name: 'Doe',
		contact_media:[
			{
                                type: 'email',
                                value: 'john.doe@paidyet.com'
                        },
			{
				type: 'phone',
				value: '5555555555'
			}
		]
	}

}

ACH Sale Transaction

{
	amount: 1234.56
	check: {
		account_holder: 'John Doe',
		account: '111111'
		routing: '999999992'
	},
	type: 'sale',
	billing_address: {
                addresss: '111 1st ave n',
                city: 'New York City',
                state: "NY",
                postal: 50001
  	}
	],
	customer: {
		first_name: 'John',
		last_name: 'Doe',
		contact_media:[
			{
                                type: 'email',
                                value: 'john.doe@paidyet.com'
                        },
			{
				type: 'phone',
				value: '5555555555'
			}
		]
	}

}

In this example the credit card will be tokenized immediately, then the amount $1,234.56 will be processed and put into a batch.  

Sale Transaction (minimal)

{
	amount: 1234.56
	credit_card: {
		number: '4111111111111111',
		exp: '04/29'
		name: 'John Doe',
		cvv: 111
	},
	type: 'sale'
}

In this example the credit card will be tokenized immediately, then the amount $1,234.56 will be authorized but will not be put into a batch until it is captured.

Auth Only Transaction (minimal)

{
	amount: 1234.56
	credit_card: {
		number: '4111111111111111',
		exp: '04/29'
		name: 'John Doe',
		cvv: 111
	},
	type: 'auth'
}

In this example the credit card has already been tokenized. The token is used to process the amount $1,234.56 and put it into a batch to settle. 

Sale Transaction (with token)

{
	amount: 1234.56
	credit_card: {
		token: 'abc12332342'
	},
	type: 'sale'
}

Data Objects

The following are the object types passed to and from the API. In some cases – particularly when sending to the API, only certain properties are necessary. These properties are denoted in the tables below.

Address

property type description
id int read-only unique identifier
address string required
city string required
state string (2) required
postal string required

ApiMessage

property type description
code int Message code. If not applicable, may be omitted or set to “0”
content string The content of the message

ApiPayload

property type description
type string The type of data being returned in the payload
items array Array of items matching the type. For instance – Transaction objects.
count int The total number of items that could have been returned matching the request criteria
pages int The total number of pages
page int The number of the page of items returned
per_page int The number of items per page of this payload

ApiResponse

property type description
messages object Object consisting of ApiMessage objects keyed by type. Types are info, warning, and error
payload ApiPayload API payload object

Authentication

property type description
subdomain string Merchant’s PaidYET subdomain [xyz.paidyet.com]  would pass in just xyz.
key string Merchant’s PaidYET api key. These can be managed in the PaidYET dashboard

Batch

property type description
id int read-only unique identifier
status string read-only open/closed
Date Opened date date that the batch was created
Date Closed date date the batch closed and was set to settle
external_id string unique identifier used to look up customer. This is not generated by PaidYET. 

Contact Media

property type description
id int read-only unique identifier
type string phone, email
value string phone or email address

Check

property type description
id int read-only unique identifier
account string ACH account number
routing string ACH routing number
accountholder string Name or business on the account
external_id string unique identifier used to look up customer. This is not generated by PaidYET.

Credit Card

property type description
id int read-only unique identifier
token string read-only / required when creating transaction
number string required when creating a new card
exp string Date in the format “MM/YY”
name string Name on the card
cvv string CVV (not saved, not returned)
funding string credit, debit, prepaid, charge, deferred debit
product_segment string consumer, business, commercial, government, all, other
issuing_country string Country code of account
issuer string Name of the issuer.
product_name string Type of card. E.g. Visa Classic
external_id string unique identifier used to look up customer. This is not generated by PaidYET.

Customer

property type description
id int read-only unique identifier
first_name string required
last_name string required
contact_media array Array of ContactMedium objects
addresses array Array of Address objects (limit 1 for now)
external_id string unique identifier used to look up customer. This is not generated by PaidYET. 

 

Custom Fields

property type description
id int read-only unique identifier
key string required
value string required

Device

property type description
key string This is the unique key that’s used when referencing this device. This is used for sending and canceling all transactions to this device.
name string The name that has been assigned to the terminal. 

Device Transaction Request

 

property type description
id int read-only unique identifier
type string

auth = auth only transaction requested
sale = sale transaction requested  (default)
cancel = cancel the device transaction request

 
amount float amount in dollars of the transaction being requested
key string This is the unique key generated for this device payment request. This is the value you will use to cancel or check on the status of this request
status string requested, transaction complete,  canceled via api, canceled via terminal, request timed out
transaction transaction This is the transaction object if a transaction was attempted on this request. This field will be filled in if the status is “transaction complete”
device device This is the device that the transaction was sent to.

Repeat

 

property type description
period string yearly, monthly, weekly, daily
interval int the number of years, months, weeks or days between repeating the transactions. For example: if the period is monthly and the interval is 3, the scheduled transaction would run every 3 months on the day of the month set under “date” in “schedule”.

Repeat Cancel

 

property type description
type string date, count
value string either a date to cancel on or a number of times that the schedule should repeat before cancelling.

Schedule

property type description
id int read-only unique identifier
date string required date / time formatted as “YYYY-MM-DD HH:MM:SS” in UTC. If the transaction is set to repeat, this date will be used to denote which day of the month, week, or year to repeat the transaction on. For example: if the date is set to Monday June 15th, the weekly would repeat on Mondays, the monthly would repeat on the 15th of each month or the yearly would repeat on June 15th each year. 
repeat Repeat optional, this is an object that sets how often the transaction repeats. If recurring payments are necessary, pass this object in with the transaction. 
cancel RepeatCancel An object that contains when the scheduled transaction should stop repeating. If transactions should repeat indefinitely, do not include this property.

Transaction

property type description
id int read-only unique identifier
amount float required amount in dollars. Must be 0 or greater. Excluding fees. Surcharge fees will automatically be added if surcharging is enabled on merchant’s account. Do not include surcharge fees in this amount
fees TransactionFees array of fees associated with this transaction. These fees will be added to the total amount charged on the card. Do not add surcharge fees here.
credit_card CreditCard required if no check included
check Check required if no credit_card included
input_method string chip, swiped, keyed, etc.
type string Optional. If omitted and amount is “0”, defaults to “auth”. If Ommitted and amount is greater than “0”, defaults to “sale”.
status string read-only approved, etc.
custom_fields CustomFields optional
source string api, etc.
avs_result bool
ip string read-only IP Address
billing_address Address
email string Customer’s email address
mobile_phone string Customer’s mobile phone for sms receipt
schedule Schedule optional
date_created string read-only date / time formatted as “YYYY-MM-DD HH:MM:SS” in UTC.
customer Customer optional
order_id
invoice string optional Invoice number
ponum string optional PO number
comments string optional comments
error bool read-only. Whether there was an error processing the transaction.
result string The result of the transaction
batch Batch read-only
send_receipt bool if this is set, a receipt will be sent to the customer’s email address.
external_id string unique identifier used to look up customer. This is not generated by PaidYET.

Transactioncapture

 

property type description
amount decimal this amount can only exceed the original auth amount if the merchant account has been approved to capture for more than the original auth. Not all accounts will allow for a capture more than the original amount. However, capturing for less than the original amount is allowed. To capture the full amount of the original auth transaction simply do not include this field.
value string either a date to cancel on or a number of times that the schedule should repeat before cancelling.

Transaction Fees

 

property type description
amount decimal total amount to be added to the transaction amount.
description string a brief note on what this fee is for.
partner id string (optional) a partner ID supplied by your payment facilitator. If you do not know what this is please do not specify.

 

Webhooks

Webhooks provide developers with automatic notifications when certain events occur in the gateway. This is a more efficient, realtime solution than repeatedly polling the api for updated information. Webhook events are delivered via HTTPS POST in a JSON format. The developer is responsible for providing a URL endpoint to receive the notification. Multiple event types can be sent to the same URL endpoint and multiple URL endpoints can be configured.

Transaction Complete

This event will trigger when any sale or auth only transaction is attempted.

Transaction events will all contain a transaction object in the payload parameter.

Transaction Changed

This event will trigger when transaction is adjusted. This includes changing the original auth amount or voiding the original transaction.

Transaction events will all contain a transaction object in the object parameter.

Batch Settled

This event will trigger when a batch is successfully settled.

Settlement events will all contain a Batch object in the object parameter.

For a complete list of Webhooks please contact us at support@paidyet.com

Test Cards

idcard_numberexpirationcvvstatusdecline_codemessageAVS ResponseCVV response
14000100011112224924123approvedm
224000100111112223924321approvedAm
234000100211112222924999approvedNm
244000100311112221924999approvedWm
24000300011112220924999declinedDeclined
34000300001112222924999declined4Pickup Card
44000300211112228924999declined5Do Not Honor
54000300311112227924999declined12Invalid transaction
64000300411112226924999declined15Invalid Issuer
74000300511112225924999declined25Unable to locate Record
84000300611112224924999declined51Insufficient Funds
94000300711112223924999declined55Invalid Pin
104000300811112222924999declined57Transaction Not Permitted
114000300911112221924999declined62Restricted Card
124000301011112228924999declined65Excess withdrawal count
134000301111112227924999declined75Allowable number of pin tries exceeded
144000301211112226924999declined78No checking account
154000301311112225924999declined97CVV failuren
214000100611112220924999approvedXm
254000100511112229924999approvedYm
264000100611112228924999approvedZm
274000100811112226924999approved1m

Test ACH

account_numberrouting_numberstatusmessage
111111999999992accepted
100999999992declinedBank routing number validation negative (ABA).
200999999992declinedBank routing number must be 9 digits.
300999999992declinedConsumer verification negative.

ACH Status List

Verifying Consumer verification is being performed.
Declined Consumer verification was negative for this transaction.
Approved Transaction was accepted and awaits Origination.
Cancelled Merchant opted to cancel this transaction.
Originated Transaction was sent to the bank.
Funded Merchant has been paid for this transaction.
Refunded Merchant opted to issue a refund for this transaction.
Returned Transaction was returned (cancelled/voided) by the bank and/or consumer.

AVS Status List

 

0 Address verification was not requested or it was requested but the transaction was declined
A  The street addresses match but the postal/ZIP code does not, or the request does not include the postal/ZIP code.
I Address information not verified
N No match. Transaction contained Postal/ZIP code only, or street
address only, or postal code and street address. Also used when transaction requests AVS but sends no AVS data.
R Retry, system unable to process
S Service not supported
U No data from Issuer/Authorization platform
W Nine character postal code matches; address does not
X Nine character postal code and address match
Y Street address and postal code match
Z Postal code matches; street address does not match or street address not included in request.
1 Cardholder name and ZIP match

 

CVV2/CVC2/CID Status List

M Match
N No Match
P Not Processed
S Merchant has indicated that Verification Code is not present on card
U Issuer is not certified and/or has not provided Visa Encryption

Subscribe to our Newsletter

    Subscribe to our Newsletter

      https://paidyet.com/wp-content/uploads/2022/08/PaidYET-Website-Footer-logo-2022-horizontal.png
      (650) 549-4357
      sales@paidyet.com
      support@paidyet.com

      Menu

      Resources

      Connect

      Payments Simplified.
      Advanced payment gateway technology for software companies.