PayFacto API - v2.0 - POST /charges

Creates a new charge for a credit card, terminal, payment token, or cash source. Set capture=false to create a pre-authorization that must be captured separately.

Prerequisites

🔑

Authentication — HTTP Basic Auth

All v2.0 endpoints use HTTP Basic Authentication. Set Authorization: Basic base64(username:password). Contact PayFacto for credentials.

🌐

Environment Base URLs

UAT: https://uat.ca.api.payfacto.cloud/payments/v1 | Production: https://ca.api.payfacto.cloud/payments/v1

📋

Content-Type

All request bodies require Content-Type: application/json.

🔄

Idempotency

Include Idempotency-Key header (max 64 chars) on POST requests. 200 = duplicate; 201 = newly created.

💵

Amounts

All monetary amounts are positive integers in cents. $12.99 = 1299.

Request

POST https://uat.ca.api.payfacto.cloud/payments/v1/charges

ℹ️

Authenticate with HTTP Basic Auth. Include Content-Type: application/json and optionally Idempotency-Key.

Request body fields

Field	Constraint	Description
amount	integer · required	Amount in cents. Must be >= 1. $12.99 = 1299.
invoiceNumber	string · required	Merchant invoice reference. Max 25 chars.
paymentMethod	object · required	Payment method. Required: `type` (CARD, TERMINAL, PAYMENT_TOKEN, CASH). Include matching sub-object.
capture	boolean · optional	Capture immediately. Default: true. Set false for pre-authorization.
billingDetail	object · optional	Customer billing address, email, first/last name, phone.
shippingDetail	object · optional	Shipping recipient details and tracking number.
statementDescriptor	string · optional	Descriptor on customer statement. Max 23 chars.
metadata	object · optional	Free-form key-value pairs stored with the charge.

paymentMethod.type values

type	Sub-object	What to include
CARD	paymentMethod.card	Include `number`, `expiry.month`, `expiry.year`. Optional: `cvv`. Supports 3DS via `card.authentication`.
TERMINAL	paymentMethod.terminal	Required: `terminalId` (UUID). Optional: `clerkId`, `cashback`, `tip`, `accountType`.
PAYMENT_TOKEN	paymentMethod.paymentToken	Required: `storedCredential.type` and `storedCredential.tokenId`.
CASH	paymentMethod.cash	Required: `terminalId`. Optional: `tip`, `clerkId`.

Request — Code Example

⚠️

Use UAT credentials during testing.

JSON — Card charge request

{
  "amount": 1299,
  "invoiceNumber": "1234567",
  "capture": true,
  "paymentMethod": {
    "type": "CARD",
    "card": {
      "number": "4111111111111111",
      "cvv": "123",
      "expiry": { "month": "05", "year": "2039" }
    }
  },
  "billingDetail": {
    "firstName": "John", "lastName": "Smith",
    "address": { "line1": "56 Sparks Street", "city": "Ottawa", "postalCode": "K5A 1S4", "country": "CA" }
  }
}

Response

Response fields (charge object)

Field	Type	Description
id	string (UUID)	Unique charge identifier. Store for all subsequent operations.
amount	integer	Amount in cents (e.g. 1299 = $12.99).
amountCaptured	integer	Total captured amount in cents.
amountRefunded	integer	Total refunded amount in cents.
billingDetail	object	Customer billing info (address, email, name, phone).
capture	boolean	Whether the charge was captured immediately.
captured	boolean	Whether an uncaptured charge has since been captured.
invoiceNumber	string	Merchant invoice reference (max 25 chars).
metadata	object	Key-value pairs for custom data.
originalTransactionTime	string (ISO 8601)	UTC timestamp of original transaction. Only on post-charge operations.
paymentMethod	object	Payment method details (type, card/terminal/token data).
refunded	boolean	Whether the charge has been fully refunded.
releaseDetail	object	Release details if the charge was released.
result	object	Auth result: `authCode`, `batch`, `declineCode`, `isoResponseCode`, `issuerMessage`.
shippingDetail	object	Shipping recipient information.
statementDescriptor	string	Merchant descriptor on customer statement (max 23 chars).
status	string	Transaction status: AUTHORIZED, CAPTURED, DECLINED, FAILED, RELEASED, SUCCEEDED, VOIDED.
transactionTime	string (ISO 8601)	UTC timestamp when this object was created.
voidDetail	object	Void details if voided.
error	object	Error object on failure. Contains `code`, `type`, `details`, `message`.

status values

status	Description
AUTHORIZED	Pre-authorization hold placed. Not yet captured.
CAPTURED	Funds captured successfully.
DECLINED	Transaction declined by the issuer.
FAILED	Transaction failed at the processing level.
RELEASED	Uncaptured pre-authorization released.
SUCCEEDED	Full transaction completed successfully.
VOIDED	Transaction voided before settlement.

result.declineCode values

declineCode	Meaning
DO_NOT_HONOR	Generic decline. Ask cardholder to use another card.
INSUFFICIENT_FUNDS	Balance too low.
EXPIRED_CARD	Card has expired.
INVALID_CVV	CVV does not match.
INVALID_NUMBER	Card number is invalid.
PICKUP_CARD	Card flagged — do not accept.
CALL_ISSUER	Refer to card issuer.
PIN_TRY_EXCEEDED	Too many incorrect PIN attempts.
CARD_VELOCITY_EXCEEDED	Transaction frequency limit exceeded.
BATCH_EXPIRED	Batch expired; re-submit.
INSERT_CARD	Contactless declined; insert chip.
ISSUER_TIMEOUT	Issuer timed out; retry.
DO_NOT_RETRY	Hard decline — do not retry.

Response — Code Examples

JSON — 201 Succeeded

{
  "id": "a1822999-099d-4fb1-a354-77be553a5b22",
  "amount": 1299,
  "amountCaptured": 1299,
  "captured": true,
  "invoiceNumber": "1234567",
  "paymentMethod": { "type": "CARD", "card": { "brand": "VISA", "lastFour": "1111" } },
  "result": { "authCode": "012345" },
  "status": "SUCCEEDED",
  "transactionTime": "2024-05-15T14:30:01Z"
}

JSON — 402 Declined

{
  "id": "b2933000-1aae-5gc2-b465-88cf664b6c33",
  "amount": 1299,
  "result": { "declineCode": "DO_NOT_HONOR" },
  "status": "DECLINED",
  "error": { "code": "ISSUER_DECLINED", "type": "CARD_ERROR", "message": "The card could not be charged." }
}

Error / HTTP Status Codes

HTTP Status	Meaning	Recommended Action
200	OK — Previously created (same idempotency key)	Check `status` field in response body
201	Created — New resource created	Store the `id` for future operations
400	Bad Request — Invalid payload	Check `error.details` and `error.invalidFields`
402	Payment Required — Issuer declined	Check `result.declineCode` — do not retry automatically
404	Not Found	Verify the ID in the request path
422	Unprocessable — Invalid state	Check `error.message`
500	Internal Server Error	Retry with backoff; contact PayFacto Support if persistent