Transaction

A Transaction is a representation of an exchange that has been made, is currently being made, or is about to be made through PaidYET's REST API.

🚧

Credit Card vs Check

Transactions require either a credit card or a check, but not both.

Properties

Property	Type	Description	Example
id	Number(integer)	A read-only unique identifier.	1234567890
amount*	Number(float)	Required amount in dollars. Must be 0 or greater. Dual Pricing / Surcharge fees will automatically be added if surcharging is enabled on merchant's account. Do not include surcharge fees in this amount.	1.07
gratuity	Number(float)	Optional tip/gratuitiy amount. For Tip Adjust, include estimate: true	.50
estimate	Boolean	The amount being authorized is an estimate and can be increased later.	true,false
fees	Array(of Fee objects)	These fees will be added to the total amount charged on the card. Do not add dual pricing / surcharge fees here.	See Fee Example
input_method	String	"chip", "swipe", `"keyed" **This is a response field only and is not passed in to the API.	"chip"
type	String	Optional. If omitted and amount is 0, defaults to "auth". If omitted and amount is greater than 0, defaults to "sale".	"auth"
status	String	Approved, Declined, Error This is a response field only and is not passed in to the API.	"approved"
custom_fields	Array(of Custom Field objects)	Custom Fields associated to the transaction.	See Custom Field Example
source	String	api, etc.	"api"
avs_result	Boolean	The AVS result. ** This is a response field only and is not passed in to the API.	true
ip	String	Read-only IP address.	"127.0.0.1"
ip_address	String	Cardholder IP address. This field is sent in to the PaidYET API and is used in the PaidYET fraud prevention tools. This is a recommended field.	"35.1.2.3"
billing_address	Object(Address object)	The billing address for the transaction.	See Address Example
email	String(email format)	The customer's email address.	"[email protected]"
phone	String	The Customer's phone number for SMS receipt	"555-555-5555"
schedule	Object(Schedule object)	The Schedule for the transaction.	See Schedule Example
date_created	String(YYYY-MM-DD HH:MM:SS) in UTC	Read-only datetime.	"2023-01-01 05:06:07"
customer	Object(Customer object)	The customer associated to the transaction. Customer's are stored in a merchant's Customer database.	See Customer Example
order_id	String	The Order ID.	"1234567890"
invoice	String	Optional invoice number.	"1234567890"
purchase_order_number	String	Optional PO number. (max 17 characters)	"1234567890"
comments	String	Optional comments about the transaction.	"A comment about the transaction."
error	String	Read-only. Contains the response code and authorization response message for the transaction. The format of the string is not guaranteed. Please see the REST API guide for more details. **This is a response field only and is not passed in to the API.	"N7: CVV2 MISMATCH"
result	String	The result of the transaction.	"OK"
lodging	Object(Lodging object)	The lodging information associated with the transaction.	See Lodging Example
batch	Object(Batch object)	The batch to which the transaction is associated.	See Batch Example
send_receipt	Boolean	If true, a receipt will be sent to the customer's email address.	true
external_id	String	Unique identifier used to look up customer. This is not generated by PaidYET.	"1234567890"
credit_card**	Object(Credit Card object)	The card associated to the transaction.	See Credit Card Examples
check**	Object(Check object)	The check associated to the transaction.	See Check Example
emv_data**	String	Collection of BER-TLV objects for EMV transactions. Please see the EMV Transaction guide for more information.	"5F2A0208405F30020701..."

Requirements

Required for all Transactions, optional when type is "capture".

**Only one of these items can be sent in the transaction, not multiple.

**This is a response field only and is not passed in to the API.

Examples

📘

Not all properties are required

With the following examples, many of the properties shown are not required. Most of them should be specified only if needed except as noted in the Requirements.

Sample Request - With a Credit Card

JSON

{
  "credit_card": {
    "billing_address": {
      "address": "1234 Test Street S.",
      "city": "Test City",
      "state": "CA",
      "postal": 50001
    },
    "number": "4000100011112224",
    "external_id": "1234567890",
    "name": "Firstname M Lastname",
    "email": "[email protected]",
    "description": "This is an example card."
  },
  "billing_address": {
    "address": "1234 Test Street S.",
    "city": "Test City",
    "state": "CA",
    "postal": 50001
  },
  "amount": 1.07,
  "type": "sale",
  "custom_fields": [
    {
      "key": "shoesize",
      "value": "9"
    }
  ],
  "email": "[email protected]",
  "order_id": "1234567890",
  "invoice": "1234567890",
  "purchase_order_number": "1234567890",
  "comments": "A comment about the transaction.",
  "send_receipt": true,
  "external_id": "1234567890"
}

Sample Response- With a Credit Card

JSON

{
  "credit_card": {
    "billing_address": {
      "address": "1234 Test Street S.",
      "city": "Test City",
      "state": "CA",
      "postal": 50001
    },
    "token": "abcd1234",
    "bin": 516693,
    "last4": "XXXXXXXXXXXX1111",
    "external_id": "1234567890",
    "type": "MasterCard",
    "name": "Firstname M Lastname",
    "email": "[email protected]",
    "description": "This is an example card.",
    "funding": "credit",
    "product_segment": "all",
    "product_name": "Visa Classic",
    "issuing_country": "US",
    "issuer": "Visa"
  },
  "billing_address": {
    "address": "1234 Test Street S.",
    "city": "Test City",
    "state": "CA",
    "postal": 50001
  },
  "batch": {
    "date_opened": "2023-01-01 05:06:07",
    "date_closed": "2023-01-01 05:06:07",
    "external_id": "1234567890"
  },
  "amount": 1.07,
  "input_method": "api",
  "type": "sale",
  "custom_fields": [
    {
      "key": "shoesize",
      "value": "9"
    }
  ],
  "source": "api",
  "avs_result": "M",
  "email": "[email protected]",
  "order_id": "1234567890",
  "invoice": "1234567890",
  "purchase_order_number": "1234567890",
  "comments": "A comment about the transaction.",
  "result": "OK",
  "send_receipt": true,
  "external_id": "1234567890"
}

Sample Request- With a Check

JSON

{
  "check": {
    "account": "111111",
    "routing": "999999992",
    "accountholder": "Firstname Lastname",
    "external_id": "1234567890"
  },
  "billing_address": {
    "address": "1234 Test Street S.",
    "city": "Test City",
    "state": "CA",
    "postal": 50001
  },
  "amount": 1.07,
  "custom_fields": [
    {
      "key": "shoesize",
      "value": "9"
    }
  ],
  "email": "[email protected]",
  "order_id": "1234567890",
  "invoice": "1234567890",
  "purchase_order_number": "1234567890",
  "comments": "A comment about the transaction.",
}

Sample Request- With EMV Data

JSON

{
  "emv_data": "5F2A0208405F30020701",
  "billing_address": {
    "address": "1234 Test Street S.",
    "city": "Test City",
    "state": "CA",
    "postal": 50001
  },
  "amount": 1.07,
  "custom_fields": [
    {
      "key": "shoesize",
      "value": "9"
    }
  ],
  "email": "[email protected]",
  "order_id": "1234567890",
  "invoice": "1234567890",
  "purchase_order_number": "1234567890",
  "comments": "A comment about the transaction.",
}