Documentation

Borgun, all rights reserved. 2017 ©

Introduction

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

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 Borgun's WCF services ask for the Service usage guide.

Environments

A test service is available for use while client is being implemented. Contact Borgun 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 Borgun, production URL and production Merchant ID. Contact Borgun 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 Borgun 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();