Payments¶

Setting up your API Key to request payments¶

The following settings need adding to be provided by clients of the payment api. They will be added to the PaymentPortalDb.PaymentClient table

Additionaly the API administrator should generate a random access code and add it to the following locations. This code is only used to authenticate the API with the payment portal doesn’t need to be used by clients of the API.

• PaymentPortalDb.PaymentClient.AccessCode
• ApiDb.ApiKeySettings[PaymentPortalApiKey] or ApiDb.ClientSettings[PaymentPortalApiKey]

Finally the API key used by the client needs to be granted PaymentInstallment:Create and PaymentInstallment:Query permissions.

Create a payment installment request¶

Sample request

{
    "LanguageCode": "en",
    "PaymentInstallmentId": "payment-2948",
    "Description": "Your EC English Course and Accommodation",
    "Amount": 400.10,
    "CurrencyIsoCode": "USD",
    "PaymentNotificationData": "any-data-or-blank",
    "Student": {
        "FirstNames": "John",
        "LastName": "Smith",
        "Email": "john.smith@example.com",
        "Address": {
            "Line1": "Flat 2 The Monnings",
            "Line2": "High Street",
            "City": "Norwich",
            "StateProvince": "Norfolk",
            "PostalCode": "JH99 9WW",
            "CountryIsoCode": "GB"
        }
    },
    "SummaryLines": [
        {
            "Amount": 200,
            "CurrencyIsoCode": "USD",
            "Description": "General English Course",
            "OptionalUnitBreakdown": {
                "NumberOfItems": 2,
                "PricePerItem": 100
            }
        },
        {
            "Amount": 200.1,
            "CurrencyIsoCode": "USD",
            "Description": "Homestay Accommodation",
            "OptionalUnitBreakdown": {
                "NumberOfItems": 2,
                "PricePerItem": 100.05
            }
        }
    ]
}

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
Content-Length: 111

{
  "PaymentUrl": "https://payments.ecenglish.com/djfdklfdsjlk",
  "ExpiryUtc": "2017-01-10T13:12:37.349Z"
}

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Cache-Control: no-cache
Content-Length: 354

<PutPaymentInstallmentResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/EcEnglish.Api.ServiceContract.Payment">
  <ExpiryUtc>2017-01-10T13:12:37.349Z</ExpiryUtc>
  <PaymentUrl>https://payments.ecenglish.com/djfdklfdsjlk</PaymentUrl>
</PutPaymentInstallmentResponse>

Fields

Show an appropiate page when the user returns to your site¶

You should show the user a page that informs them of the result of their payment when they return to your site.

The user will be redirected back to the page on your site that you specified when you Setup your system to create payments. The code parameter on the URL will contain the value of the PaymentInstallmentId that was specified when the payment installment request was created.

http://www.mysite.com/some-page?code=payment-2948

You can use the code query string parameter to check the status of the payment which will allow you to show an appropiate message to the customer

Sample request

{ "PaymentInstallmentId": "payment-2948" }

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
Content-Length: 194

{
  "PaymentInstallmentId": "payment-2948",
  "Status": "SuccessfullyPaid",
  "PaymentNotificationData": "any-data-or-blank",
  "PaymentUrl": "https://payments.ecenglish.com/djfdklfdsjlk"
}

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Cache-Control: no-cache
Content-Length: 465

<GetPaymentInstallmentResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/EcEnglish.Api.ServiceContract.Payment">
  <PaymentInstallmentId>payment-2948</PaymentInstallmentId>
  <PaymentNotificationData>any-data-or-blank</PaymentNotificationData>
  <PaymentUrl>https://payments.ecenglish.com/djfdklfdsjlk</PaymentUrl>
  <Status>SuccessfullyPaid</Status>
</GetPaymentInstallmentResponse>

Fields

Handle notifications about the results of payments¶

Successful and unsuccessful payments will be posted to the azure service bus queues that were setup previously. You must use the EcEnglish.Messaging.ServiceBusServer nuget package to consume the messages as this provides the required fault tolerance and reporting of failures.

Example Success Message

{
    "PaymentInstallmentId": "payment-2948",
    "Amount": 400.1,
    "PaymentNotificationData": "any-data-or-blank",
    "CurrencyIsoCode": "USD",
    "WasSuccessful": true
}

Example Failure Message

{
    "PaymentInstallmentId": "payment-2948",
    "PaymentNotificationData": "any-data-or-blank",
    "WasSuccessful": false
}