Accept Your First Payment
Process a test payment using the YardPay Pro API in under 5 minutes. You'll create an invoice, retrieve payment methods, and submit a card payment.
- A sandbox API key (
sk_test_) — see the Authentication guide - A tool for making HTTP requests (cURL, Postman, or your code editor)
Create a Test Invoice
Payments in YardPay Pro are processed against invoices. Create a simple test invoice first:
curl -X POST /v1/invoice \
-H "Content-Type: application/json" \
-H "x-api-key: sk_test_YOUR_API_KEY" \
-d '{
"description": "Test payment",
"currencyCode": "JMD",
"items": [
{
"name": "Test Item",
"unitCost": 100.00,
"quantity": 1,
"invoiceItemTypeId": "Product"
}
],
"sourceInfo": {
"firstName": "Test",
"lastName": "Customer",
"email": "[email protected]"
}
}'Save the id and identifier from the response — you'll need them for the next steps.
Get Available Payment Methods
Query the available payment methods for your invoice. This tells you which card types and payment options are enabled for your merchant account.
curl -X GET /v1/invoice/{invoiceId}/PaymentMethods \
-H "x-api-key: sk_test_YOUR_API_KEY"The response includes each method's id (the paymentOptionId you'll use next). For card payments, look for entries with paymentMethodId: "CreditCard".
Process the Payment
Submit a payment using a test card number. In sandbox mode, use 4111 1111 1111 1111 with any future expiry and any 3-digit CVV.
curl -X POST /api/payment/payinvoice \
-H "Content-Type: application/json" \
-H "x-api-key: sk_test_YOUR_API_KEY" \
-d '{
"invoiceIdentifier": "YOUR_INVOICE_IDENTIFIER",
"paymentOptionId": 1,
"card": {
"name": "Test Customer",
"cardNumber": "4111111111111111",
"expiryDate": "12/28",
"cvv": "123"
},
"billingAddress": {
"firstName": "Test",
"lastName": "Customer",
"addressLine1": "123 Main St",
"city": "Kingston",
"country": "JM"
}
}'Handle the Response
A successful payment returns isSuccess: true. Check the response to determine next steps:
// Success response
{
"referenceNumber": "PAY-20240315-001",
"amountPaid": 100.00,
"paymentStatusId": "Success",
"isSuccess": true,
"approvalAction": "None"
}| approvalAction | Meaning |
|---|---|
| None | Payment completed — you're done! |
| Redirect | 3D Secure required — redirect the user to approvalDataOrUrl |
| QrCode | Display a QR code for the user to scan |
import axios from 'axios';
const client = axios.create({
baseURL: window.location.origin,
headers: {
'Content-Type': 'application/json',
'x-api-key': 'sk_test_YOUR_API_KEY',
},
});
// 1. Create invoice
const { data: invoice } = await client.post('/v1/invoice', {
description: 'Test payment',
currencyCode: 'JMD',
items: [
{ name: 'Widget', unitCost: 100, quantity: 1, invoiceItemTypeId: 'Product' },
],
sourceInfo: {
firstName: 'Test', lastName: 'Customer', email: '[email protected]',
},
});
// 2. Get payment methods
const { data: methods } = await client.get(
`/v1/invoice/${invoice.id}/PaymentMethods`
);
const cardOption = methods.value.find(m => m.paymentMethodId === 'CreditCard');
// 3. Pay
const { data: payment } = await client.post('/api/payment/payinvoice', {
invoiceIdentifier: invoice.identifier,
paymentOptionId: cardOption.id,
card: {
name: 'Test Customer',
cardNumber: '4111111111111111',
expiryDate: '12/28',
cvv: '123',
},
});
// 4. Handle result
if (payment.isSuccess) {
if (payment.approvalAction === 'Redirect') {
// 3D Secure — redirect user
window.location.href = payment.approvalDataOrUrl;
} else {
console.log('Payment successful:', payment.referenceNumber);
}
} else {
console.error('Payment failed:', payment.hostMessage);
}| Card Number | Brand | Behavior |
|---|---|---|
| 4111 1111 1111 1111 | Visa | Succeeds immediately |
| 5500 0000 0000 0004 | Mastercard | Succeeds immediately |
| 4000 0000 0000 3220 | Visa | Triggers 3D Secure redirect |
| 4000 0000 0000 0002 | Visa | Declines with "insufficient funds" |
Use any future expiry date and any 3-digit CVV for all test cards.