REST API - Accept Payments Online | Advanced Payment Gateway Technology

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.

Pagination

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

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

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

Point-of-Sale (POS) devices can be controlled from the PaidYET API. The POS api can be found here .

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

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

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

id	card_number	expiration	cvv	status	decline_code	message
1	4000100011112224	924	123	approved
22	4000100111112223	924	321	approved
23	4000100211112222	924	999	approved
24	4000100311112221	924	999	approved
2	4000300011112220	924	999	declined		Declined
3	4000300001112222	924	999	declined	4	Pickup Card
4	4000300211112228	924	999	declined	5	Do Not Honor
5	4000300311112227	924	999	declined	12	Invalid transaction
6	4000300411112226	924	999	declined	15	Invalid Issuer
7	4000300511112225	924	999	declined	25	Unable to locate Record
8	4000300611112224	924	999	declined	51	Insufficient Funds
9	4000300711112223	924	999	declined	55	Invalid Pin
10	4000300811112222	924	999	declined	57	Transaction Not Permitted
11	4000300911112221	924	999	declined	62	Restricted Card
12	4000301011112228	924	999	declined	65	Excess withdrawal count
13	4000301111112227	924	999	declined	75	Allowable number of pin tries exceeded
14	4000301211112226	924	999	declined	78	No checking account
15	4000301311112225	924	999	declined	97	CVV failure
21	4000100611112220	924	999	approved

Test ACH

account_number	routing_number	status	message
111111	999999992	accepted
100	999999992	declined	Bank routing number validation negative (ABA).
200	999999992	declined	Bank routing number must be 9 digits.
300	999999992	declined	Consumer verification negative.

ACH Status List

Verifying	Consumer verification is being performed.
Declined	Consumer verification was negative for this transaction.
Accepted	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.