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
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. |
{
subdomain: 'xyz'
key: '12345798abcdefg'
}
{
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
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
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. |
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 |
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. |
{
amount: 1234.56
type: 'sale'
}
{
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. |
{
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. |
{
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 |
{
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.
{
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'
}
]
}
}
{
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.
{
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.
{
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.
{
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
|
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 | |
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 | AVS Response | CVV response |
---|---|---|---|---|---|---|---|---|
1 | 4000100011112224 | 924 | 123 | approved | m | |||
22 | 4000100111112223 | 924 | 321 | approved | A | m | ||
23 | 4000100211112222 | 924 | 999 | approved | N | m | ||
24 | 4000100311112221 | 924 | 999 | approved | W | m | ||
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 | n | |
21 | 4000100611112220 | 924 | 999 | approved | X | m | ||
25 | 4000100511112229 | 924 | 999 | approved | Y | m | ||
26 | 4000100611112228 | 924 | 999 | approved | Z | m | ||
27 | 4000100811112226 | 924 | 999 | approved | 1 | m |
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. |
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 |