Syntch Gateway API

PatchContract

Administration - Recurring Billing Contracts

**Requires Authentication**
Requires the role:	Merchant

The following routes are available for this service:
PATCH	/merchants/{merchantKey}/customers/{customerKey}/contracts/{contractKey}	Update a recurring billing contract for a customer.

**PatchContract** Parameters:
Name	Parameter	Data Type	Required	Description
MerchantKey	path	integer	Yes	The key of the merchant.
CustomerKey	path	integer	Yes	The customer key.
ContractKey	path	integer	Yes	The key of the contract to patch.
Token	model	string	No	The token representing customer payment data.
BillAmount	model	decimal?	No	Amount billed each time the contract comes due in DD.CC format.
StartDate	model	DateTime?	No	Date that the contract becomes effective in YYYY/MM/DD format. The start date must be greater than today’s date. The StartDate represents the first time the customer will be billed per the contract. Future bill dates are calculated using the BillingPeriod and BillingInterval parameters.
EndDate	model	DateTime?	No	Date that the contract is completed in YYYY/MM/DD format. The end date must be greater than the start date.
MerchantContractName	model	string	No	Merchant defined friendly name for this contract
MerchantContractId	model	string	No	Merchant defined identification for this contract. This is not a unique identifier within the gateway but rather a way for the merchant to identify a contract.
BillingPeriod	model	BillingPeriod?	No	This value is used in conjunction with the BillingInterval to compute the next bill date for a contract. The system will automatically account for 31 day months and/or leap years. For example: Recurring billing is set to run once monthly. The contract start date is set for the 31st. If the next month only has 30 days, recurring billing will automatically run the transaction on the 30th. Allowable Values Week Month Year
ActivationStatus	model	ActivationStatus?	No	Indicates whether the contract is currently active (reviewed each day for pending payments due) or inactive Allowable Values Active Inactive Deleted
MaxFailures	model	int?	No	The number of times the system will try to re-process a failed payment before the contract is placed in suspended state. If left blank, the default value is zero (0). A MaxFailure = 0 means that the system will not try to reprocess a failed payment. IMPORTANT: When a payment fails to process and the MaxFailures parameter is set to a value greater than zero (0), all future payments will be ignored until the failed payment is either successfully processed or the contract is suspended.
BillingInterval	model	int?	No	This value is used in conjunction with the BillingPeriod to compute the next bill date for a contract. Allowable Values 2 4 14 21 28
FailureInterval	model	int?	No	The interval in days between attempts to retry processing a failed payment.
FailurePeriod	model	FailurePeriod?	No	Sets the FailureInterval time period. Allowable Values Week
EmailCustomerReceiptOption	model	EmailCustomerReceiptOption?	No	Determines under what circumstances a receipt will be emailed to the customer. Allowable Values OnApproval OnDecline All
EmailMerchant	model	bool?	No	Indicates whether the system will send an email to the merchant after successfully processing a scheduled payment.
EmailCustomer	model	bool?	No	Indicates whether the system will send an email to the customer after successfully processing a scheduled payment.
EmailMerchantFailure	model	bool?	No	Indicates whether the system will send an email to the merchant after failing to process a scheduled payment.
EmailCustomerFailure	model	bool?	No	Indicates whether the system will send an email to the customer after failing to process a scheduled payment.
TaxAmount	model	decimal?	No	Tax amount applied to the BillAmount in DD.CC format.
TotalAmount	model	decimal?	No	Total amount billed, including tax, each time the contract comes due in DD.CC format.
MaxAmount	model	decimal?	No	Maximum amount allowed for the full term of this contract in DD.CC format.
CustomFields	model	List<ContractCustomField>	No	A collection of custom field objects. The complete set of custom fields will be replaced on a patch. For example, if a contract currently has two custom fields and a patch request contains just one custom field, the updated contract will contain only one custom field - the one passed in on the patch request.

**BillingPeriod** Enum:
DAY
WEEK
MONTH
YEAR

**ActivationStatus** Enum:
Pending
Active
Inactive
Deleted

**FailurePeriod** Enum:
DAY
WEEK

**EmailCustomerReceiptOption** Enum:
Never
OnApproval
OnDecline
All

**ContractCustomField** Parameters:
Name	Parameter	Data Type	Required	Description
CustomValue	form	string	No
CustomKey	form	int	No

**ContractDetail** Parameters:
Name	Parameter	Data Type	Required
ContractKey	form	int	No
MerchantKey	form	int	No
CustomerKey	form	int	No
Token	form	string	No
BillAmount	form	decimal	No
StartDate	form	DateTime?	No
EndDate	form	DateTime?	No
MerchantContractName	form	string	No
MerchantContractId	form	string	No
BillingInterval	form	int?	No
BillingPeriod	form	string	No
ActivationStatus	form	string	No
MaxFailures	form	int?	No
FailureInterval	form	int?	No
FailurePeriod	form	string	No
EmailMerchant	form	bool	No
EmailCustomer	form	bool	No
EmailMerchantFailure	form	bool	No
EmailCustomerFailure	form	bool	No
TaxAmount	form	decimal	No
TotalAmount	form	decimal	No
MaxAmount	form	decimal?	No
CustomFields	form	List<ContractCustomField>	No
AmountBillsToDate	form	decimal	No
EmailCustomerReceiptOption	form	string	No
NextBillDate	form	DateTime?	No
NumberPayments	form	int?	No
NumberBillsToDate	form	int?	No
NumberFailures	form	int?	No

To override the Content-type in your clients, use the HTTP Accept Header, append the .jsv suffix or ?format=jsv

HTTP + JSV

The following are sample HTTP requests and responses. The placeholders shown need to be replaced with actual values.

PATCH /merchants/{merchantKey}/customers/{customerKey}/contracts/{contractKey} HTTP/1.1 
Host: syntch.simpay.net 
Accept: text/jsv
Content-Type: text/jsv
Content-Length: length

{
	MerchantKey: 0,
	CustomerKey: 0,
	ContractKey: 0,
	Token: String,
	BillAmount: 0,
	StartDate: 0001-01-01,
	EndDate: 0001-01-01,
	MerchantContractName: String,
	MerchantContractId: String,
	BillingPeriod: DAY,
	ActivationStatus: Pending,
	MaxFailures: 0,
	BillingInterval: 0,
	FailureInterval: 0,
	FailurePeriod: DAY,
	EmailCustomerReceiptOption: Never,
	EmailMerchant: False,
	EmailCustomer: False,
	EmailMerchantFailure: False,
	EmailCustomerFailure: False,
	TaxAmount: 0,
	TotalAmount: 0,
	MaxAmount: 0,
	CustomFields: 
	[
		{
			CustomValue: String,
			CustomKey: 0
		}
	]
}

HTTP/1.1 200 OK
Content-Type: text/jsv
Content-Length: length

{
	ContractKey: 0,
	MerchantKey: 0,
	CustomerKey: 0,
	Token: String,
	BillAmount: 0,
	StartDate: 0001-01-01,
	EndDate: 0001-01-01,
	MerchantContractName: String,
	MerchantContractId: String,
	BillingInterval: 0,
	BillingPeriod: String,
	ActivationStatus: String,
	MaxFailures: 0,
	FailureInterval: 0,
	FailurePeriod: String,
	EmailMerchant: False,
	EmailCustomer: False,
	EmailMerchantFailure: False,
	EmailCustomerFailure: False,
	TaxAmount: 0,
	TotalAmount: 0,
	MaxAmount: 0,
	CustomFields: 
	[
		{
			CustomValue: String,
			CustomKey: 0
		}
	],
	AmountBillsToDate: 0,
	EmailCustomerReceiptOption: String,
	NextBillDate: 0001-01-01,
	NumberPayments: 0,
	NumberBillsToDate: 0,
	NumberFailures: 0
}

Syntch Gateway API

PatchContract

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

HTTP + JSV