Welcome to the
Developer Hub.
Comprehensive documentation and guides to help you start integrating with PaidYET's robust REST API and our full suite of integration options — from hosted checkout to JavaScript widgets, webhooks, and POS devices. This hub will provide a summary. For additional documentation, please access our ReadMe Docs at paidyet.readme.io.
Quick links
API endpoints — transactions
Our Services
We provide a variety of services to make payments easy with PaidYET. Below you'll find a quick summary of each service and links for more detailed information.
Integrations
API Keys
PaidYET offers two types of API keys depending on how you're integrating. Understanding which to use is the first step in building your integration. See paidyet.readme.io/docs/api-keys for full details.
REST API
Our fast, secure REST API allows merchants to process transactions through their PaidYET merchant account. Our REST API uses our backend fraud protection to eliminate fraud and remove liability from the merchant.
Base URL
Authentication
All requests must include your API key in the request header. Pass your API key as the value for the Authorization header.
Content-Type: application/json
Transaction endpoints
Example: create a transaction
"type": "sale",
"amount": 49.99,
"credit_card": {
"name": "John Doe",
"number": "4000100011112224",
"exp": "12/34",
"cvv": "123"
}
}
Sandbox
Sandbox is a risk-free environment that allows PaidYET service integrators to test their integrations without using real cards — eliminating the risk of leaking sensitive card information while testing.
https://api.sandbox-paidyet.com/v3Transaction gateway
The PaidYET sandbox does not process live transactions and passes no credit card data to settlement platforms. All transactions use our "Mock" processor, which works only with the test cards listed below. All other cards produce an "Invalid Card" error. We do not store any credit card data on invalid cards and keep no logs of invalid attempts due to PCI DSS rules.
Email system
The sandbox environment is not intended to send emails to external accounts and should not be used for testing email receipts at scale. Sandbox emails use a lower-volume platform and will differ slightly from production emails.
Test cards
| Card number | Exp | CVV | Status | Decline code | Message |
|---|---|---|---|---|---|
| 4000100011112224 | 932 | 123 | approved | — | — |
| 4000100111112223 | 932 | 321 | approved | — | AVS: A |
| 4000100211112222 | 932 | 999 | approved | — | AVS: N |
| 4000100311112221 | 932 | 999 | approved | — | AVS: W |
| 4000100411112220 | 932 | 999 | approved | — | AVS: X |
| 4000100511112229 | 932 | 999 | approved | — | AVS: Y |
| 4000100611112228 | 932 | 999 | approved | — | AVS: Z |
| 345678901234564 | 932 | 999 | approved | — | Name + address + ZIP match |
| 371449635398431 | 932 | 999 | approved | — | Name + address match |
| 378282246310005 | 932 | 999 | approved | — | Name matches |
| 4000300011112220 | 932 | 999 | declined | — | Declined |
| 4000300001112222 | 932 | 999 | declined | 4 | Pickup Card |
| 4000300211112228 | 932 | 999 | declined | 5 | Do Not Honor |
| 4000300311112227 | 932 | 999 | declined | 12 | Invalid transaction |
| 4000300411112226 | 932 | 999 | declined | 15 | Invalid Issuer |
| 4000300511112225 | 932 | 999 | declined | 25 | Unable to locate record |
| 4000300611112224 | 932 | 999 | declined | 51 | Insufficient Funds |
| 4000300711112223 | 932 | 999 | declined | 55 | Invalid Pin |
| 4000300811112222 | 932 | 999 | declined | 57 | Transaction Not Permitted |
| 4000300911112221 | 932 | 999 | declined | 62 | Restricted Card |
| 4000301011112228 | 932 | 999 | declined | 65 | Excess withdrawal count |
| 4000301311112225 | 932 | 999 | declined | 97 | CVV failure |
Test ACH accounts
| Account number | Routing | Status | Decline code |
|---|---|---|---|
| 111111 | 999999992 | accepted | — |
| 100 | 999999992 | declined | 100 |
| 200 | 999999992 | declined | 200 |
| 300 | 999999992 | declined | 300 |
Hosted Checkout
Hosted Checkout is our rapid-setup hosted payment page solution that sends a customer from the merchant's site to our secure payment page when it's time to make a payment. Once payment is complete, the customer is returned to the merchant's site. Integrated in minutes — relieves the merchant of PCI liabilities entirely.
Transaction setup
Our system allows merchants to send customers to their custom payment link via POST or redirect. When payment is done, we send them back to any custom results page. The results page must be SSL encrypted.
results_url is posted directly to the PaidYET payment page, the posted value will be used instead.Sample — use PaidYET's results page
Amount <input name="amount">
Invoice <input name="invoice">
Description <input name="description">
<button type="submit">Submit</button>
</form>
Sample — use your own results page
Sample — testing
Change [paymentlink] to test to use the sandbox payment page.
Amount <input name="amount">
Invoice <input name="invoice">
Description <input name="description">
<button type="submit">Submit</button>
</form>
Test card numbers
| Card number | Expiration | CVV2 | Result |
|---|---|---|---|
| 4000100011112224 | 0919 | any | Success |
| 4000300011112220 | 0919 | any | Declined |
Post fields
Fields marked ** are editable by the user on the payment page.
| Field | Description |
|---|---|
| results_url | URL that transaction details will be posted back to |
| amount | The USD amount that will be charged |
| invoice | A unique PaidYET transaction number |
| description ** | The description of the transaction |
| email ** | Email address of the cardholder |
| address ** | Residing address of the cardholder |
| city / state / zip ** | Cardholder location fields |
| phone ** | Phone number of the cardholder |
| fName / lName ** | First and last name of the cardholder |
JavaScript Widget
The JavaScript Widget is our embeddable credit card field plugin. It allows merchants to provide a seamless payment experience without handling or storing sensitive cardholder information — added in a few simple lines of code.
Implementation
<div id="card-errors"></div>
<button onclick="PaidYET.processPayment(callback);">Process</button>
Replace
{paypage subdomain} with the subdomain of your paypage.
PaidYET.renderForm(settings)
if (e.success) {
alert('Successful Request')
}
}
// Callback event object contains:
// e.success (Boolean), e.token (String),
// e.type (String), e.cc_last4 (String)
Sandbox mode
Settings object
| Field | Type | Required | Description | Default |
|---|---|---|---|---|
| element | string | Yes | ID of the HTML element to insert the credit card form into | — |
| mode | string | No | sale — process immediately · cardonfile — tokenize for later use | sale |
| amount | decimal | No | Default charge amount. Required if hideamount is true. Ignored in cardonfile mode. | — |
| note | string | No | Value sent with transaction, appears in reports | — |
| fname / lname | string | No | First and last name of cardholder | — |
| string | No | Email address of cardholder | — | |
| hideamount | boolean | No | Hide the amount field. Must pass amount separately if true. | false |
| hidenotes | boolean | No | Hide the notes field | false |
| hidezip | boolean | No | Hide the zip field. Pass zip separately if required and hidden. | false |
| style | object | No | JSON object for styling widget elements (see Style Object below) | — |
Full example
var settings = {
amount: '1.00',
element: "card-element-cof",
hidenotes: true,
hidezip: false,
style: {
paddingTop: '7px',
paddingBottom: '7px',
borderRadius: '2px',
borderColor: '#efefef',
cvv: {
display: 'none'
}
}
}
PaidYET.renderForm(settings)
Webhooks
With webhooks, users may define an endpoint that will be called when an event occurs — such as sending batch results when a batch closes. Webhooks enable real-time event-driven integrations with PaidYET.
Events
batch.closedbatch.createdbatch.failedWebhook response format
"event": "batch.closed",
"data": [
{
"id": 22642,
"status": "closed",
"amount": "1.23",
"merchant": { "name": "Acme Anvils" },
"source": "tsys",
"device": {
"name": "Front Office Terminal",
"sn": "123456789"
},
"number_transactions": 1,
"date_opened": "2023-11-21 13:07:39",
"date_closed": "2023-11-22 16:20:54"
}
]
}
The event property value changes based on which event was fired.
Adding webhooks to your account
SDK (.NET)
Our .NET Software Development Kit can be used with backend implementations in a .NET context to simplify the coding process to our Advanced API. It wraps the REST API in a native .NET library so you can integrate PaidYET without writing raw HTTP requests.
Terminals & Devices
Our state-of-the-art POS devices use an Android interface to integrate between cardholders and PaidYET's secure payment processing infrastructure. They allow merchants to process transactions through our gateway at a physical point of sale.
Fraud Modules
PaidYET's SecuredYET™ fraud module provides backend fraud protection that eliminates fraud and removes liability from the merchant. It runs automatically on all transactions processed through the REST API.
Industry-Specific Features
PaidYET offers a variety of industry-specific features to help you seamlessly integrate our services according to your business needs.
Lodging
PaidYET provides tools for merchants enrolled in lodging-specific pricing to qualify for lower transaction rates. Lodging transactions use a specific object structure with check-in, incremental auth, and check-out flows.
Check-in (auth)
Lodging transactions intended for check-in should use a type of auth and include a lodging object.
"type": "auth",
"amount": 1.23,
"credit_card": {
"name": "John Doe",
"exp": "12/34",
"number": "4111111111111111"
},
"lodging": {
"duration": 1,
"check_in_date": "2024-01-01",
"check_out_date": "2024-01-02",
"room_rate": 12.34
}
}
Incremental authorization
After check-in, PATCH the original transaction to add additional charges to the bill.
"type": "incremental",
"amount": 1.23
}
Check-out (capture)
For check-out, PATCH the original transaction with a type of sale.
"type": "sale"
}
ACH
Automated Clearing House (also known as Electronic Checking) allows ACH-approved merchants to offer their customers the ability to pay by bank account instead of card. ACH rates depend on industry — ranging from 0% to 0.5% + $0.25–$2.50.
ACH transaction statuses
| Status | Definition |
|---|---|
| Processed | Newly accepted and successfully authenticated transaction |
| Downloaded | Downloaded to back-office system — temporary status |
| BO Exception | Transaction failed back office (BO) processes |
| Originated | Successfully validated through BO and presented to the FED |
| Funded | Transaction has been paid to the merchant |
| Refunded | Transaction credited back to the consumer |
| Invalid Return | Returned with invalid account information |
| NSF Return | Returned for non-sufficient funds |
| Chargeback Return | Returned unauthorized or authorization revoked |
| Returned | All other return types not defined above |
| IsLateReturn | Attribute (not a status) — transaction was Processed, Originated, and Funded but returned after funding |
Advanced Transactions
PaidYET offers advanced transaction features for complex commerce scenarios — dual pricing, transaction fees, scheduled payments, recurring billing, and auth-only authorizations.
Dual Pricing / Surcharge
Dual Pricing / Surcharge allows the collection of processing fees that a merchant incurs at the time the transaction is performed. The merchant must disclose to the customer which fees are present at the time the transaction is performed.
For full implementation documentation, see paidyet.readme.io/docs/surcharge.
Auth Only Transactions
An Authorization Only (Auth Only) transaction reserves funds from a customer's credit card without processing the payment. This verifies the card is valid and has sufficient funds without capturing the charge.
How it works
To create an Auth Only transaction, set the type field to auth in your transaction request. The funds are reserved on the customer's card but not settled until you submit a capture request.
"type": "auth",
"amount": 49.99,
"credit_card": {
"name": "John Doe",
"number": "4000100011112224",
"exp": "12/34",
"cvv": "123"
}
}
To capture the reserved funds, use the capture endpoint:
Integrations
PaidYET offers a variety of integration options that allow you to utilize our secure payment services. Choose the approach that fits your product and engineering resources.
eCommerce
PaidYET provides the tools for recurring billing and card-on-file transactions when buying and selling goods through online media. See paidyet.readme.io/docs/ecommerce for full details.
Retail (Terminals)
PaidYET provides the gateway that integrates with our state-of-the-art POS devices for card-present retail environments. See paidyet.readme.io/docs/retail-terminals for full details.
Collections
PaidYET is debt repayment certified, allowing certified merchants to qualify at lower transaction rates. See paidyet.readme.io/docs/collections for full details.
Payment Facilitator
A payment facilitator is a provider that allows its customers to accept payments using their merchant account. A PayFac handles the deposits, fees, and risk of all customers boarded under the account. See paidyet.readme.io/docs/payfac for full details.
Transaction Fees
Our services allow usage of transaction fees — any fees a merchant has identified that they want to disclose to the customer at the time of payment. See paidyet.readme.io/docs/transaction-fees for full details.
Schedules
Transaction scheduling allows transactions to be set to run on a future date. Pass a schedule object when creating a transaction via the REST API. See paidyet.readme.io/docs/schedules for full details.
Recurring
PaidYET's recurring transaction options allow transactions to be performed on a regular time interval — daily, weekly, monthly, or custom schedules. See paidyet.readme.io/docs/recurring for full details.
Gateway Emulator
The PaidYET Gateway Emulator allows developers to simulate gateway behavior for testing purposes. See paidyet.readme.io/docs/gateway-emulators for full details.
QDI
The PaidYET QDI (Quick Device Interface) integration option. See paidyet.readme.io/docs/qdi for full details.