Submit card and customer info for a product

Processes a card payment for the specified product. Returns HTTP 200 for all transaction outcomes (success, decline, 3DS pending, etc.). Non-200 responses indicate a request-level failure with no transaction created.

Typical response flow

1. On success: info = "Success", subscribeSuccess and/or chargeSuccess are true.
2. On decline: info = "Error", chargeSuccess = false, statusId indicates the decline reason.
3. On 3DS required: info = "Pending", threeDSecureId is populated — call POST /api/{productId}/3ds to complete.
4. On pre-processing error (no transaction): info is one of "Failed", "LimitReached", "UserBlocked", or "None", and statusId = 0. See the error field and the Error & Decline Handling Guide.

POST /api/{productId}

Submit card and customer info for a product

cURL

curl --request POST \
  --url https://test.paysight.io/api/{productId} \
  --header 'Authorization: <api-key>' \
  --header 'ClientId: <clientid>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "card": {
    "name": "<string>",
    "pan": "<string>",
    "expiryMonth": 123,
    "expiryYear": 123,
    "cvv": "<string>",
    "bin": "<string>",
    "lastFour": "<string>",
    "brand": "<string>"
  },
  "email": "<string>",
  "amount": 123,
  "paysightSession": "<string>",
  "partnerSession": "<string>",
  "phone": "<string>",
  "address": {
    "firstName": "<string>",
    "lastName": "<string>",
    "street": "<string>",
    "city": "<string>",
    "state": "<string>",
    "zip": "<string>",
    "country": "<string>"
  },
  "shippingAddress": {
    "firstName": "<string>",
    "lastName": "<string>",
    "street": "<string>",
    "city": "<string>",
    "state": "<string>",
    "zip": "<string>",
    "country": "<string>"
  },
  "mid": "<string>",
  "props": {},
  "campaignId": 123,
  "affiliateId": 123,
  "campaignName": "<string>",
  "affiliateName": "<string>",
  "subAffiliate": "<string>",
  "trackhouseClickId": "<string>",
  "threeDSecure": {
    "enabled": true,
    "cancelOnFail": true
  },
  "useragent": "<string>",
  "ip": "<string>",
  "cascade": true,
  "applePay": true,
  "shopify": {
    "savePaymentMethod": true,
    "usePreviousPaymentMethod": true,
    "optIn": true
  }
}
'

200

success

{
  "info": "Success",
  "subscribeSuccess": true,
  "chargeSuccess": true,
  "statusId": 3616,
  "orderId": 1000123,
  "submitOrderId": 1000123,
  "transactionId": "a1b2c3d4-0000-0000-0000-000000000001",
  "amount": 9.99,
  "mid": "MID123",
  "descriptor": "EXAMPLE.COM",
  "bin": "41111111",
  "last4": "1111",
  "binCountry": "US",
  "networkTokenized": false,
  "applePay": false,
  "googlePay": false,
  "declineSalvage": false,
  "gatewayResponses": [],
  "subscriptionId": 500
}

Authorizations

Authorization · string · header · required

Your Paysight API key. Send the raw key value — do not prefix with Bearer. Copy it from https://app.paysight.io/settings/account.

Headers

ClientId · string · required

Your Paysight tenant ID (parent company ID). Find it at https://app.paysight.io/settings/account or https://app.paysight.io/management/companies.

Path Parameters

productId · integer · required

ID of the Paysight product. This can be found at https://app.paysight.io/management/products

Body

application/json

card · object · required

Show child attributes

email · string · required

Customer email address

amount · number · required

Amount to charge in the transaction

paysightSession · string

Unique session identifier from Paysight. Either this or partnerSession must be provided.

partnerSession · string

Session identifier from the partner's system. Either this or paysightSession must be provided. Keep this value at 50 characters or fewer so it is persisted for transaction-webhook correlation.

Maximum string length: 50

phone · string

Customer phone number

address · object

Show child attributes

shippingAddress · object

Show child attributes

mid · string

Override to explicitly set for the transaction. It will override the Paysight logic for selecting the MID. Omit by default.

props · object

Custom metadata as key-value pairs

Show child attributes

campaignId · integer · deprecated

Deprecated internal Paysight-assigned campaign ID. Omit this field and use campaignName for a campaign name, alias, or your identifier.

affiliateId · integer · deprecated

Deprecated internal Paysight-assigned traffic-source or affiliate ID. Omit this field and use affiliateName for a name, alias, or your identifier.

campaignName · string

Name, alias, or your identifier for the campaign. Paysight resolves the matching campaign or creates a campaign record for a new value.

affiliateName · string

Name, alias, or your identifier for the affiliate or traffic source. Paysight resolves the matching affiliate or creates an affiliate record for a new value.

subAffiliate · string

Sub-affiliate identifier, if applicable. This can be passed in the format 'primarysubid_secondarysubId' (or simply primarysubid if no secondary source is present). These fields are available as breakdowns in Reporting as Primary Sub ID and Secondary Sub ID

trackhouseClickId · string

Tracking click ID from Trackhouse. Not required

threeDSecure · object

Show child attributes

useragent · string

User-Agent header from client request

ip · string

IP address of the client

cascade · boolean

If true, will attempt a cascade, i.e. a second authorization attempt on another MID if selection conditions are met

applePay · boolean

Set to true if this transaction should use Apple Pay

shopify · object

Shopify-specific checkout options. Only required for Shopify integrations.

Show child attributes

Response

200

application/json

Card submission result. Covers all transaction outcomes including success, all decline types, 3DS pending, already-subscribed, and pre-processing errors. Inspect info and statusId to determine the specific outcome. See the SubmitResult schema for the full statusId reference table.

paysightSession · string

Paysight session identifier

partnerSession · string

Partner session identifier

subscribeSuccess · boolean

Indicates if the subscription was created successfully.

chargeSuccess · boolean

Indicates if the charge transaction was fully captured.

info · enum<string>

High-level outcome of the submission. Possible values:

• Success – Transaction completed successfully. subscribeSuccess and/or chargeSuccess will be true.
• Error – Transaction-level failure. A transaction was attempted; check statusId for the decline reason.
• Failed – Pre-processing validation failure; no transaction was logged. Check the error field.
• LimitReached – A rate or frequency limit was exceeded; no transaction was logged. Check the error field.
• UserBlocked – The user, card, BIN, or email is blocked; no transaction was logged. Check the error field.
• AlreadySubscribed – Customer is already subscribed; no new transaction was created.
• Pending – Awaiting 3D Secure authentication; threeDSecureId will be populated. Call POST /api/{productId}/3ds to complete.
• RedirectRequired – A redirect is required to complete the transaction.

Available options: Success, Error, Failed, LimitReached, UserBlocked, None, AlreadySubscribed, Pending, RedirectRequired

error · string

Specific error message. Interpretation depends on the accompanying info value.

When info is "Error" (statusId > 0, transaction was attempted): This field contains the status description from the payment processor corresponding to the statusId value. See the statusId reference tables for the full list.

When info is "Failed" (no transaction logged, statusId: 0):

• "Blocked" – Request blocked at the platform level.
• "Blocked Card" – The specific card is blocked.
• "Invalid expiry" – Card expiryMonth or expiryYear is zero or missing.
• "Invalid CVV" – CVV/CVC value is invalid or missing.
• "Invalid CC Number" – Card number failed validation.
• "Invalid Email" – Email address is invalid or missing.
• "VISA cards not Supported" – VISA cards are not accepted for this product/MID.
• "Mastercard cards not supported" – Mastercard cards are not accepted for this product/MID.
• "Discover cards not supported" – Discover cards are not accepted for this product/MID.
• "AMEX cards not supported" – American Express cards are not accepted for this product/MID.
• "MAESTRO cards not supported" – Maestro cards are not accepted for this product/MID.
• "Bin and Last4 required along with Encrypted data" – bin and lastFour must be provided when submitting encrypted card data.
• "Specified Mid not found" – The mid field does not match any known MID.
• "Specified Mid does not belong to Tenant account" – The mid field references a MID from a different tenant.

When info is "LimitReached" (no transaction logged, statusId: 0):

• "CC entered too many times in quick succession" – The card number has been submitted too frequently in a short window.
• "Email entered too many times for this product" – The email address has been used too many times for this product.

When info is "UserBlocked" (no transaction logged, statusId: 0):

• "Blocked card" – Card BIN is from a blocked country.
• "Blocked" – User is blacklisted (by email, card number, or BIN).

email · string

Email address associated with the transaction.

message · string

General message about the result. For pre-processing errors this mirrors the error field. For 3D Secure pending flows this will be empty; check threeDSecureId instead.

orderId · integer

Order identifier for the subscription or charge record.

descriptor · string

Credit card descriptor that will appear on the cardholder's statement.

mid · string

Merchant ID (MID number) used for the transaction.

threeDSecureId · string

Identifier for the 3D Secure session. Populated only when info is "Pending". Pass this value to POST /api/{productId}/3ds to complete the authentication flow. Null or empty in all other cases.

transactionId · string

Unique transaction identifier from the payment processor.

amount · number

Amount charged in the transaction currency.

statusId · integer

Paysight transaction status code. 0 means no transaction was logged (pre-validation failure or unexpected error). All other values represent a processed transaction outcome.

For the complete reference with retry guidance see the Error & Decline Handling Guide.

---

Successful

ID	Status
2636	Transaction succeeded
3367	Preauthorized
3616	Approved
4165	Card Verified
4173	SUCCEEDED
4257	Transaction Approved

---

Issuer Declines

The issuing bank rejected the transaction. The card or account is the primary cause.

ID	Status
2674	Transaction declined for unknown reason
2677	Transaction declined by authorization system
2683	Transaction declined (suspecting manipulation)
2684	Transaction declined (stolen card)
2690	Transaction declined (card lost)
2693	Transaction declined (restricted card)
2695	Transaction declined (transaction not permitted)
2696	Transaction declined (pick up card)
2882	Account or user is blacklisted
3185	Account Closed
3290	Suspected Fraud
3613	Issuer Declined
3614	Issuer Declined MCC
3617	Declined
3618	Do not honor
3621	Transaction not allowed
3629	Call issuer for further information
3631	Lost card
3632	Stolen card
3635	Declined - Stop all recurring payments
3637	Declined - Update cardholder data available
3638	Declined - Retry in a few days
3640	Transaction error returned by processor
3654	Transaction declined (additional customer authentication required)
3821	Pick up card - F
3822	Pick up card - SF
3823	Pick up card - NF
4111	ScaRequiredError
4174	ADDRESS_VERIFICATION_FAILED_RISK_RULES
4175	AUTHORIZATION_EXPIRED_OR_ALREADY_CAPTURED
4176	BANK_ACCOUNT_CLOSED
4177	BANK_ACCOUNT_FROZEN
4178	CALL_ISSUER
4179	CANCELLATION_VIA_API
4180	CANCELLATION_VIA_DEVICE
4181	CARD_ACCOUNT_CLOSED
4182	CARD_NETWORK_ERROR
4183	CARD_NOT_ACTIVATED_OR_BLOCKED
4184	CARD_NOT_SUPPORTED
4185	CARDHOLDER_PREVENTED_RECURRING_TRANSACTION
4186	COMMUNICATION_ERROR
4187	CVV_FAILED_RISK_RULES
4191	DO_NOT_HONOR
4192	DUPLICATE_TRANSACTION
4193	EXCEEDED_CARDHOLDER_INPUT_TIME_LIMIT
4194	EXCEEDS_APPROVAL_LIMIT
4195	EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT
4197	FRAUD_DETECTED
4198	FRAUD_DETECTED_BY_FINIX
4199	FRAUD_DETECTED_BY_ISSUER
4200	GENERIC_DECLINE
4202	INCOMPLETE_TRANSACTION
4205	INVALID_AMOUNT
4211	INVALID_ISSUER
4212	INVALID_ROUTING_NUMBER
4213	INVALID_TRANSACTION
4214	ISSUER_POLICY_VIOLATION
4215	LOST_OR_STOLEN_CARD
4216	MAX_TRANSACTION_AMOUNT_EXCEEDED
4217	NO_BANK_ACCOUNT_FOUND
4218	NON_TRANSACTION_ACCOUNT
4219	PAYMENT_STOPPED
4220	PICK_UP_CARD
4221	RESTRICTED_CARD
4222	RESUBMIT_TRANSACTION
4223	ALLOWABLE_NUMBER_OF_PIN_ENTRY_TRIES_EXCEEDED
4224	CANNOT_VERIFY_PIN
4226	CRYPTOGRAPHIC_ERROR_FOUND_IN_PIN
4227	ERROR
4228	EXCEEDS_APPROVAL_AMOUNT_LIMIT
4229	FILE_TEMPORARILY_NOT_AVAILABLE
4230	FINANCIAL_INSTITUTION_NOT_FOUND
4232	INVALID_AMOUNT_OR_CURRENCY
4233	INVALID_MERCHANT
4234	ISSUER_INOPERATIVE
4235	LOST_CARD_PICK_UP_FRAUD_ACCOUNT
4236	NEGATIVE_RESULTS
4237	NO_ACTION_TAKEN
4238	NO_CHECKING_ACCOUNT
4239	NO_CREDIT_ACCOUNT
4240	NO_SAVINGS_ACCOUNT
4241	NO_SUCH_ISSUER
4243	PICK_UP_CARD_FRAUD_ACCOUNT
4244	PICK_UP_CARD_NO_FRAUD
4245	RE_ENTER_TRANSACTION
4246	REFER_TO_CARD_ISSUER
4247	STOLEN_CARD_PICK_UP_FRAUD_ACCOUNT
4248	STOP_PAYMENT_ORDER
4249	SURCHARGE_AMOUNT_NOT_SUPPORTED
4250	SUSPECTED_FRAUD
4251	TRANSACTION_AMOUNT_EXCEEDS_PREAUTHORIZED_APPROVAL_AMOUNT
4252	TRANSACTION_DOES_NOT_FULFILL_AML_REQUIREMENT
4253	TRANSACTION_NOT_COMPLETED_LAW_VIOLATION
4254	UNABLE_TO_LOCATE_RECORD
4255	Rejected (NMI Fraud block)
4256	TRANSACTION_NOT_PERMITTED
4265	Card Type Not Accepted
4266	ACH Not Accepted
4267	AVS Mismatch
4268	Merchant Does Not Accept Card Type
4279	Declined - Pick Up Card
4280	Voice Authorization Required
4290	Card Type Not Accepted by Processor
4303	Declined - Fraud Score Too High
4307	Declined - AVS and Card Code Filter

---

Insufficient Funds

ID	Status
2687	Transaction declined (limit exceeded)
3512	Insufficient Funds
3619	Insufficient funds
3620	Over limit
4203	INSUFFICIENT_FUNDS
4242	NOT_SUFFICIENT_FUNDS
4281	Insufficient Funds

---

Invalid Card Details

The card number, expiry, CVV, or holder name is invalid or failed verification.

ID	Status
2676	Transaction declined (invalid card)
2682	Transaction declined (wrong expiry date)
2707	Transaction declined (invalid CVV — amount may be reserved for a few business days)
2708	Transaction declined (UserAccount Number/ID unknown)
3137	Card Expired
3142	cc/bank account holder not valid
3149	Invalid cc number/brand combination
3256	Invalid credit card number
3625	Expired card
3627	Invalid card security code
3628	Invalid PIN
4105	InvalidCardError
4196	EXPIRED_CARD
4201	INACTIVE_CARD
4204	INVALID_ACCOUNT_NUMBER
4206	INVALID_BANK_ACCOUNT_NUMBER
4207	INVALID_BANK_ACCOUNT_VALIDATION_CHECK
4208	INVALID_CARD
4209	INVALID_CARD_NUMBER_OR_EXPIRED_CARD
4210	INVALID_CVV
4225	CARD_AUTHENTICATION_FAILED
4231	INCORRECT_PIN
4258	Invalid Credit Card Number
4259	Invalid Expiration Date
4260	Credit Card Expired
4274	Invalid Amount
4275	Invalid Account Number
4276	Invalid ABA Code
4277	Card Code Mismatch
4282	Invalid Card Code
4295	Required Field Missing
4299	Invalid Credit Card Number Format
4306	Declined - Card Code Mismatch

---

Other / System Errors

Gateway configuration issues, platform-level blocks, duplicate detection, communication failures, and other non-issuer, non-card errors. No transaction may be retried without resolving the underlying cause.

ID	Status
0	None — no transaction logged
2	Failed
1614	Unsubscribed
1789	Submitted (gateway-level submission status)
2680	Transaction declined (amount exceeds credit)
2681	Transaction declined (format error)
2686	Transaction declined (too many invalid tries)
2858	AVS Check Failed (amount reserved but will be released)
2884	Email blacklisted
2887	BIN Blacklisted (Paysight)
2890	Duplicate Transaction
2892	Max transactions per account already exceeded
2913	Channel/Merchant is disabled (no processing possible)
2927	Channel/Merchant not configured for this payment type
2931	Invalid payment data (currency or sub type not configured)
3027	Test accounts not allowed in production
3089	Invalid authentication information
3140	Request contains no cc/bank account holder
3448	Failed AVS
3610	OMIT STATE
3622	Incorrect payment information
3623	No such card issuer
3624	No card number on file with issuer
3636	Declined - Stop this recurring program
3639	Transaction was rejected by gateway
3641	Invalid merchant configuration
3642	Merchant account is inactive
3643	Communication error
3644	Communication error with issuer
3645	Duplicate transaction at processor
3646	Processor format error
3647	Invalid transaction information
3648	Processor feature not available
3649	Unsupported card type
3808	BIN country blocked
3809	Amount exceeds max ticket
3814	Name Blacklisted
3818	Invalid US State Code
4079	ConfigurationError
4080	CommunicationError
4082	AccountError
4083	TimeoutError
4088	InputDataMissingError
4089	InputDataFormatError
4090	InputDataInvalidError
4093	WorkflowError
4095	ReferenceWorkflowError
4104	ProcessingError
4107	ExpiredCardError
4115	CardBlacklistError
4116	BinBlacklistError
4119	BlacklistError
4130	IrisFilterDeclinedError
4135	IpNotWhitelistedError
4159	RemoteSystemError
4160	RemoteConfigurationError
4162	RemoteWorkflowError
4166	Authorized then Voided/Cancelled
4167	Strong Customer Authentication Required
4168	BIN Blacklisted (Client)
4169	Daily threshold exceeded
4170	Custom descriptors are not allowed
4171	Specified API key not found
4172	3DS Failed
4261	Duplicate Transaction
4262	Invalid Merchant Authentication
4263	Invalid Transaction ID
4264	Transaction Not Found
4269	Transaction Not Eligible for Settlement
4270	Transaction Already Settled
4271	Authorization Code Required
4272	Invalid Relay Response URL
4273	Processing Error - Try Again
4278	Transaction Security Failure
4283	Transaction Under Review
4284	Processing Error - Connection Issue
4285	Processing Error - System Timeout
4286	Processing Error - Gateway Issue
4287	Elavon Configuration Error
4288	Processing Error - Retry Available
4289	Processing Error - Server Issue
4291	Paymentech Configuration Error
4292	Processor Configuration Invalid
4293	FDC Configuration Error
4294	Merchant Password Invalid
4296	VITAL Configuration Error
4297	Processor Setup Error
4298	Settlement Failed After Authorization
4300	Global Payment System Configuration Error
4301	Invalid Currency Code
4302	Transaction Must Be Encrypted
4304	Missing Required Field Information
4305	Invalid Terminal ID
4308	Session Expired or Invalid
4309	Settlement Amount Exceeds Authorization
4310	Partial Reversals Not Accepted
4311	Amount Exceeds Maximum Allowed
4312	Transaction Awaiting Settlement
4313	Credit Exceeds Original Amount
4314	Client Notification Failed

declineSalvage · boolean

true if the customer was subscribed even though the charge was declined (e.g. a grace-period subscription on an insufficient-funds decline). In this case subscribeSuccess may be true while chargeSuccess is false.

merchantAccountId · integer

Paysight internal ID for the Merchant Account used for the transaction.

midPortalUrl · string

Optional portal URL defined on the Paysight Brand entry. See https://app.paysight.io/management/brands/

bin · string

Bank Identification Number (first 8 digits of PAN).

binCountry · string

Country of the BIN (ISO 3166-1 alpha-2) if available, e.g. "US".

last4 · string

Last 4 digits of the card number.

eci · string

Electronic Commerce Indicator for 3D Secure transactions. "02" / "05" = fully authenticated (liability shift applies). "01" / "06" = attempted authentication.

networkTokenized · boolean

Indicates whether the transaction was processed using a network token.

submitOrderId · integer

Identifier for the card-submit event. When the submit does not result in a subscription this equals orderId. When a subscription is created (even if the charge fails) this value differs from orderId.

applePay · boolean

Indicates if the transaction was processed as an Apple Pay payment.

googlePay · boolean

Indicates if the transaction was processed as a Google Pay payment.

gatewayResponses · object[]

Raw gateway responses from each processing attempt (useful for debugging declines).

Show child attributes

subscriptionId · integer

Paysight subscription ID created by this submit. 0 if no subscription was created.