Introduction

This document describes Recurring Payments WCF services provided by SaltPay. User must be registered to load the services and have proper access to use them. Communication is via SSL on a webserver at SaltPay.

Usage guidelines

It is recommended to use "Service Reference" rather than "Web Reference" when connecting from a .NET 3.0+ client. This is a more recent approach and is designed to work with WCF services. A fully functional demo in .Net can be provided to payment service developers.
For more details on how to consume SaltPay's WCF services ask for the Service usage guide.

Environments

A test service is available for use while client is being implemented. Contact SaltPay for test access information.

The following merchant contract ID can be used while testing.

Merchant ID: 9256684

When implementation is completed this information has to be replaced with the proper user account supplied by SaltPay, production URL and production Merchant ID. Contact SaltPay for production access.

Lastest service URLs

Test:
https://test.borgun.is/recurringpayments/recurringpayment.svc
Production:
https://services.borgun.is/recurringpayments_2_2/recurringpayment.svc

Service overview

Service method name	Description
CreateRecurringPayment	Creates a recurring payment that should be charged once or more with a given month interval.
GetDeniedTransactions	Get a list of transactions that have been processed but were denied.
CancelDeniedTransaction	Cancel transaction that was denied.
CorrectDeniedTransaction	Correct transaction that was denied.
GetBatches	Get list of processed batches.
GetBatchTransactions	Get list of transactions in a given batch.
GetTransaction	Get detail information about a transaction.
GetCardInfo	Get information about the credit card type, status, issuer etc

Service documentation

Objects

ResultStatus

The response contains a ResultStatus which contains ResultCode, ResultText and ErrorMessage to describe result.

ResultCode	ResultText	ErrorMessage
0	Success	NULL
10	Informational	f.e: Not found
20	Warning	A warning message
30	Error	Error condition explained

RecurringPaymentContract

Field	Type	Description
Id	Long	Recurring Paymend ID
MerchantContractNumber	String	Merchant ID
CreditCardNumber	String	Credit card number
VirtualCardnumber	String	Virtual card number
Reference	String	Reference field, max 255 characters
SsnReference	String	Reference field 2, ideal for customer ID number or SSN, max 15 characters
Created	DateTime	Creation date of contract
FirstPayment	DateTime	Activation date, date of first payment
LastPayment	DateTime	Close date of payment contract. After this date the recurring payment will be closed
Amount	Decimal	Amount of each payment
CurrencyCode	String	Currency code of transaction. Currency code is not set by client but depends on merchant contract settings
TotalPaymentsIndefinite	Bool	Indicates if payment count is known or if it should continue until explicitly stopped
TotalPaymentsPaid	Int	Number of payments placed
Automatic	Bool	Indicates if the recurring payment is automatic or manual. All recurring payments are created automatic by this service
PaymentInterval	int	Months between payments
PaymentIntervalType	String	Type of intervalue, all recurring payments are created with type monthly by this service
LastProcessed	DateTime	Date of last payment process
Finished	Bool	Indicates if recurring payment contract has finished, either been closed or all payments paid

RecurringPaymentBatch

Field	Type	Description
MerchantContractNumber	String	Merchant ID
BatchNumber	String	Batch number
BatchDate	DateTime	Date of batch
TotalAmount	Decimal	Total transaction amount
TotalInProcess	Decimal	Total amount of transactions still in process
TotalAuthorized	Decimal	Total amount of authorized transactions
TotalDeclined	Decimal	Total amount of declined transactions
TotalCorrected	Decimal	Total amount of corrected declined transactions
TotalOmitted	Decimal	Total amount of cancelled declined transactions
ContractType	RecurringPaymentContractType	Type of recurring contract Contribution EasyPayment RecurringPayment
BatchType	RecurringPaymentBatchType	Type of batch Automatic Manual Resent

RecurringPaymentTransaction

Field	Type	Description
Id	Long	ID of the transaction
RecurringPaymentContractId	Long	ID of the recurring payment contract created with CreateRecurringPayment
MerchantContractNumber	String	Merchant ID
BatchNumber	String	Number of the batch containing the transaction
SlipNumber	String	Transaction slip number
CardNumber	String	Credit card number, unmasked when a single transaction is retrieved using GetTransaction otherwise masked.
TransactionNumber	String	Transaction number
Amount	Decimal	The amount of the transaction
CurrencyCode	String	ISO currency code
TransactionDate	DateTime	Date of transaction
TransactionStatus	RecurringPaymentTransactionStatus	Current status of the transactions Ok Declined InProcess WaitingToBeSent Corrected Omitted
TransactionType	RecurringPaymentTransactionType	Transaction type: Automatic, Manual, Resent
ReferenceId	Long	Transaction reference ID
Message	String	Reason for declining the transaction, empty if ok
PaymentContractReference	String	Recurring payment contract reference
PaymentContractSSN	String	Recurring payment contract SSN reference

CardInfo

Field	Type	Description
Cardnumber	String	Credit card number
PaymentType	String	Possible types B = charge C = credit/revolving P = prepaid D = debit
PaymentTypeText	String	Text accompanying the type
CardStatus	String	Card status, e.g. closed
IssuingBank	String	Bank code of issuer
IssuerName	String	Name of issuer
DomesticOnly	Boolean	True if only domestic use is allowed
CardScheme	String	Name of card scheme
CardnumberLength	Int	Length of card number, usually 15 or 16 digits
CardDescription	String	Name of credit card type, gold, silver, platinum etc.
InstallmentsAllowed	Boolean	True it is allowed to charge installments to the card
RecurringAllowed	Boolean	True if it is allowed to charge recurring payments to the card
ReplacementCard	String	If the given card number has been closed and a new card number is available otherwise empty. This replacement also occures automatically on payment contract when charging a card

Service functionality

CreateRecurringPayment

Summary
Submit recurring payment that should be charge more than once with a given month interval. If recurring payment should only be charged once totalPayments is set to 1. To create a recurring payment that will be charged until explicitly ended set totalPayments to 0.

(*) Payments dated 1st - 6th of every month are not processed until the 7th to increase probability of successful authorization. After the first payment, all payments are processed on the 7th of every month.

(**) Please note that when creating a monthly payment a cardholder can be charged twice on the same period if first payment is scheduled late in a month. To avoid this always set the first payment to the beginning of next month, at least if payment is being created after middle of the month.

Parameters

Name	Type	Description
Status	ResultStatus	Out parameter that contains the result status
MerchantContractNumber	String	Merchant contract number
CreditCardNumber	String	Credit card number
Amount	Decimal	Amount to be charged each time.
TotalPayments	Int	Number of payments to be charged.
PaymentInterval	Int	Months between payments, 1 for every month.
FirstPayment	DateTime	Date when first payment should be processed. () (*)
Reference	String	Payment reference for merchant.
SsnReference	String	Customer SSN reference for merchant.

UpdateRecurringPayment

Summary
Updates an existing recurring payment contract. Merchant contract number and first payment can not be updated.

(*) Please note that when creating a monthly payment a cardholder can be charged twice on the same period if first payment is scheduled late in a month. To avoid this always set the first payment to the beginning of next month, at least if payment is being created after middle of the month.

Parameters

Name		Description
status	ResultStatus	Out parameter that contains the result status
id	Long	The recurring payment ID
creditCardNumber	String	Credit card number
amount	Decimal	Amount to be charged each time.
totalPayments	Int	Number of payments to be charged.
paymentInterval	Int	Months between payments, 1 for every month. (*)
reference	String	Payment reference for merchant.
ssnReference	string	Customer SSN reference for merchant.

GetRecurringPaymentContracts

Summary
Returns a list of recurring payment contracts for a given merchant contract number. Returns a list of RecurringPaymentContract.

Parameters

Name		Description
status	ResultStatus	Out parameter that contains the result status
merchantContractNumber	String	Merchant contract number
Finished	bool	Indicates if open or closed recurring payments should be retrieved.

GetRecurringPaymentContract

Summary
Gets a single recurring payment contract by ID. ID is returned by CreateRecurringPayment.

Returns a RecurringPaymentContract.

Parameters

Name	Description
status	ResultStatus	Out parameter that contains the result status
merchantContractNumber	String	Merchant contract number
Id	long	The recurring payment ID

GetRecurringPaymentContractsByReference

Summary
Gets recurring payments by the reference value.

Returns a list of RecurringPaymentContract.

Parameters

Name		Description
status	ResultStatus	Out parameter that contains the result status
merchantContractNumber	String	Merchant contract number
Reference	String	The reference to search by
Finished	Bool	The status of the recurring payment contract

GetDeniedTransactions

Summary
Get transactions that have been processed but were denied.

For each payment the service will try and charge the card once, if unsuccessful the transaction needs to be manually resent with CorrectDeniedTransaction function or cancelled if it's unlikely to ever be successful. In such cases the payment contract should be closed with MarkRecurringPaymentContractAsFinished .

Returns an array of RecurringPaymentTransaction.

Parameters

Name		Description
status	ResultStatus	Out parameter that contains the result status
merchantContractNumber	String	Merchant contract number

CancelDeniedTransaction

Summary
Cancel transaction that was denied.

Parameters

Name		Description
status	ResultStatus	Out parameter that contains the result status
transactionId	Long	Id of transaction to cancel (omit)

CorrectDeniedTransaction

Summary
Resend a previously denied transaction, either with the original credit card number or a new one. If a new card number is used, the payment contract is updated with the new card number.

Parameters

Name		Description
status	ResultStatus	Out parameter that contains the result status
transactionId	Long	Id of transaction to correct
creditCardNumber	string	Credit card number for transaction, can be changed from original transaction, otherwise send original card number

GetBatches

Summary
Get list of processed batches.

Returns an array of RecurringPaymentBatch.

Parameters

Name		Description
status	ResultStatus	Out parameter that contains the result status
merchantContractNumber	String	Merchant contract number
from	DateTime	First day of the batch period to get
to	DateTime	Last day of the batch period to get

GetBatchTransactions

Summary
Get list of transactions in a given batch. Card numbers are masked in the list.

Returns an array of RecurringPaymentTransaction.

Parameters

Name		Description
status	ResultStatus	Out parameter that contains the result status
batchNumber	String	Batch number

GetTransaction

Summary
Get detail information about a single transaction with an unmasked credit card number.|

Returns RecurringPaymentTransaction.

Parameters

Name		Description
status	ResultStatus	Out parameter that contains the result status
transactionId	Long	Id of transaction

GetTransactionByContract

Summary
Retrieves all transactions charged to a given acount.

Returns a list of RecurringPaymentTransaction object.

Parameters

Name	Description
status	Out parameter for run result
contractId	ID of recurring payment contract, returned by create service function or by get recurring payment functions.
merchantContractNumber	Merchant contract number the recurring payment contract belongs to

MarkRecurringPaymentContractAsFinished

Summary
Closes a recurring payment contract immediatelly. After a contract has been marked finished it will not be charged again and can't be reopened.

Parameters

Name	Description
status	Out parameter for run result
merchantContractNumber	Merchant contract number the recurring payment contract belongs to
id	Id of the contract to close

GetCardInfo

Summary
Basic information about a credit card, such as the type, issuer etc. If a card has been re-issued, or otherwise replaced, a new card number is returned. Card may exists and be valid even if ResultCode is 10 (no data found), since SaltPay does not have information on all issued cards.

Returns a CardInfo object.

Parameters

Name	Description
status	Out parameter for run result
cardNumber	The credit card number on which to get basic information

Code Example

    RecurringPaymentService.RecurringPaymentsClient client =
        new RecurringPaymentService.RecurringPaymentsClient();
    client.ClientCredentials.UserName.UserName = username;
    client.ClientCredentials.UserName.Password = password;

    // Create a payment contract
    RecurringPaymentService.ResultStatus status = client.CreateRecurringPayment(
        merchantId,
        cardNumber,
        amount,
        0,              /* payment count is indefinite */
        1,              /* card will be charged every month */
        DateTime.Now,   /* payment contract activates immediately */
        reference,
        idNumber);
    if (status.resultCode == "0")
    {
        Console.WriteLine("Payment contract successfully created");   
    }

    // Retrieve all transactions in a batch
    RecurringPaymentService.RecurringPaymentTransaction[] transactions
        = client.GetBatchTransactions(out status, batchNumber);
    if (status.resultCode == "0")
    {
        Console.WriteLine(
            "Batch {0} has {1} transactions",
            batchNumber,
            transactions.Count());
    }

    // Retrieve all denied transactions on the merchant
    RecurringPaymentService.RecurringPaymentTransaction[] denied =
        client.GetDeniedTransactions(out status, merchantId);
    if (status.resultCode == "0")
    {
        Console.WriteLine(
            "{0} denied transaction on merchant {1}",
            transactions.Count(),
            merchantId);
    }

    // Close the connection
    client.Close();

Documentation

Introduction

Usage guidelines

Environments

Service overview

Service documentation

Objects

ResultStatus

RecurringPaymentContract

RecurringPaymentBatch

RecurringPaymentTransaction

CardInfo

Service functionality

CreateRecurringPayment

UpdateRecurringPayment

GetRecurringPaymentContracts

GetRecurringPaymentContract

GetRecurringPaymentContractsByReference

GetDeniedTransactions

CancelDeniedTransaction

CorrectDeniedTransaction

GetBatches

GetBatchTransactions

GetTransaction

GetTransactionByContract

MarkRecurringPaymentContractAsFinished

GetCardInfo

Code Example