Syntch Gateway API

PutContract

Administration - Recurring Billing Contracts

**Requires Authentication**
Requires the role:	Merchant

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

**PutContract** Parameters:
Name	Parameter	Data Type	Required	Description
ContractKey	path	integer	Yes	The key of the contract to replace.

**ContractRequest** Parameters:
Name	Parameter	Data Type	Required	Description
MerchantKey	path	integer	Yes	The key of the merchant.
CustomerKey	path	integer	Yes	The customer key.
Token	model	string	Yes	The token representing customer payment data.
BillAmount	model	decimal	Yes	Amount billed each time the contract comes due in DD.CC format.
StartDate	model	DateTime	Yes	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	Default is 3000/01/01 - equivalent to no end date. 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	Default is None. Merchant defined friendly name for this contract
MerchantContractId	model	string	No	Default is None. 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.
MaxFailures	model	int	No	Default is 10. 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	Default is 1. 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	Default is 1. The interval in days between attempts to retry processing a failed payment.
EmailMerchant	model	bool	No	Default is false. Indicates whether the system will send an email to the merchant after successfully processing a scheduled payment.
EmailCustomer	model	bool	No	Default is false. Indicates whether the system will send an email to the customer after successfully processing a scheduled payment.
EmailMerchantFailure	model	bool	No	Default is false. Indicates whether the system will send an email to the merchant after failing to process a scheduled payment.
EmailCustomerFailure	model	bool	No	Default is false. Indicates whether the system will send an email to the customer after failing to process a scheduled payment.
TaxAmount	model	decimal	No	Default is 0.00. Tax amount applied to the BillAmount in DD.CC format.
TotalAmount	model	decimal	No	Default is 0.00. Total amount billed, including tax, each time the contract comes due in DD.CC format.
MaxAmount	model	decimal	No	Default is 0.00. 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. These custom fields will be added to the contract.
BillingPeriod	model	BillingPeriod	No	Default is Month. 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	Default is Active. Indicates whether the contract is currently active (reviewed each day for pending payments due) or inactive Allowable Values Active Inactive Deleted
FailurePeriod	model	FailurePeriod	No	Default is Day. Sets the FailureInterval time period. Allowable Values WEEK
EmailCustomerReceiptOption	model	EmailCustomerReceiptOption	No	Default is Never. Determines under what circumstances a receipt will be emailed to the customer. Allowable Values OnApproval OnDecline All

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

**BillingPeriod** Enum:
DAY
WEEK
MONTH
YEAR

**ActivationStatus** Enum:
Pending
Active
Inactive
Deleted

**FailurePeriod** Enum:
DAY
WEEK

**EmailCustomerReceiptOption** Enum:
Never
OnApproval
OnDecline
All

**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 .xml suffix or ?format=xml

HTTP + XML

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

PUT /merchants/{merchantKey}/customers/{customerKey}/contracts/{contractKey} HTTP/1.1 
Host: syntch.simpay.net 
Accept: application/xml
Content-Type: application/xml
Content-Length: length

<PutContract xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/Gateway.RestApi.Contracts.Requests">
  <ActivationStatus>Pending</ActivationStatus>
  <BillAmount>0</BillAmount>
  <BillingInterval>0</BillingInterval>
  <BillingPeriod>DAY</BillingPeriod>
  <CustomFields xmlns:d2p1="http://schemas.datacontract.org/2004/07/Gateway.RestApi.Contracts.DTO">
    <d2p1:ContractCustomField>
      <d2p1:CustomKey>0</d2p1:CustomKey>
      <d2p1:CustomValue>String</d2p1:CustomValue>
    </d2p1:ContractCustomField>
  </CustomFields>
  <CustomerKey>0</CustomerKey>
  <EmailCustomer>false</EmailCustomer>
  <EmailCustomerFailure>false</EmailCustomerFailure>
  <EmailCustomerReceiptOption>Never</EmailCustomerReceiptOption>
  <EmailMerchant>false</EmailMerchant>
  <EmailMerchantFailure>false</EmailMerchantFailure>
  <EndDate>0001-01-01T00:00:00</EndDate>
  <FailureInterval>0</FailureInterval>
  <FailurePeriod>DAY</FailurePeriod>
  <MaxAmount>0</MaxAmount>
  <MaxFailures>0</MaxFailures>
  <MerchantContractId>String</MerchantContractId>
  <MerchantContractName>String</MerchantContractName>
  <MerchantKey>0</MerchantKey>
  <StartDate>0001-01-01T00:00:00</StartDate>
  <TaxAmount>0</TaxAmount>
  <Token>String</Token>
  <TotalAmount>0</TotalAmount>
  <ContractKey>0</ContractKey>
</PutContract>

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: length

<ContractDetail xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/Gateway.RestApi.Contracts.Responses">
  <ActivationStatus>String</ActivationStatus>
  <AmountBillsToDate>0</AmountBillsToDate>
  <BillAmount>0</BillAmount>
  <BillingInterval>0</BillingInterval>
  <BillingPeriod>String</BillingPeriod>
  <ContractKey>0</ContractKey>
  <CustomFields xmlns:d2p1="http://schemas.datacontract.org/2004/07/Gateway.RestApi.Contracts.DTO">
    <d2p1:ContractCustomField>
      <d2p1:CustomKey>0</d2p1:CustomKey>
      <d2p1:CustomValue>String</d2p1:CustomValue>
    </d2p1:ContractCustomField>
  </CustomFields>
  <CustomerKey>0</CustomerKey>
  <EmailCustomer>false</EmailCustomer>
  <EmailCustomerFailure>false</EmailCustomerFailure>
  <EmailCustomerReceiptOption>String</EmailCustomerReceiptOption>
  <EmailMerchant>false</EmailMerchant>
  <EmailMerchantFailure>false</EmailMerchantFailure>
  <EndDate>0001-01-01T00:00:00</EndDate>
  <FailureInterval>0</FailureInterval>
  <FailurePeriod>String</FailurePeriod>
  <MaxAmount>0</MaxAmount>
  <MaxFailures>0</MaxFailures>
  <MerchantContractId>String</MerchantContractId>
  <MerchantContractName>String</MerchantContractName>
  <MerchantKey>0</MerchantKey>
  <NextBillDate>0001-01-01T00:00:00</NextBillDate>
  <NumberBillsToDate>0</NumberBillsToDate>
  <NumberFailures>0</NumberFailures>
  <NumberPayments>0</NumberPayments>
  <StartDate>0001-01-01T00:00:00</StartDate>
  <TaxAmount>0</TaxAmount>
  <Token>String</Token>
  <TotalAmount>0</TotalAmount>
</ContractDetail>

Syntch Gateway API

PutContract

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

HTTP + XML