PeiApi NuGet package

Summary

PeiApi is a NuGet package that implements calls to some methods in the https://api.pei.is/docs/ui/index that also includes authentication methods to interact with the API.

Dependencies

Newtonsoft.Json.dll (version 13.0.1)

System.Net.Http.Formatting.dll (from Microsoft.AspNet.WebApi.Client version 5.2.7)

Usage

Create a PeiService object configured for staging (testing environment) or production using the PeiApiConfiguration class.

Then use this PeiService object to interact with the API as you see fit.

PeiApiConfiguration

Includes the settings used to connect to the environment and creates a PeiService object that has those environment options set up.

Before calling .CreateService(), either use .WithStagingAuth() to configure it for staging or just .WithAuth() for production environments.

  • For the staging environment, use client "democlient" and secret "demosecret"

  • Contact customer support for access to the production environment

Method

Description

Method

Description

WithStagingAuth(client,secret)

Configures the authentication settings for staging

WithAuth(client,secret)

Configures the authentication settings for production

CreateService()

Creates the PeiService object with the configured settings

PeiService

Includes implemented method calls to the Pei API. All these calls are asynchronous Task methods that can be awaited.

Similar to how the sections are in the Pei API, these methods are split into three sections, PurchaseAccess, Orders and PinOrders.

Currently implemented method calls are listed here, along with further documentation for what each does and what their inputs are.

In cases where there are no objects to return, the methods return HttpResponseMessage with relevant information about the method's execution. See the https://api.pei.is/docs/ui/index Swagger docs for more detailed information about possible HTTP Status Codes and their meaning for the output.

Orders

Method

Description

Input

Output

Pei API method

Method

Description

Input

Output

Pei API method

SubmitOrderAsync

Add an order to Pei

OrderModel

SubmitOrderResult

POST: /api/orders

PayOrderAsync

Purchase an order for a buyer. The merchant (merchantId in the submitted order) is required to have access to purchasing orders for the buyer.

PurchaseAccessOrderModel

PurchaseAccessOrderResult

POST: /api/orders/pay

OrderModel

Name

Type

Required

Description

Name

Type

Required

Description

MerchantId

int

Yes

Unique Pei ID for a merchant

Buyer

BuyerModel

Yes

A buyer model, cannot be null. See BuyerModel for details

Amount

decimal

Yes

Total amount

Reference

string

No

The merchant’s own reference for the order

ExpirationDate

DateTime?

No

An expiration date for the order. Default (when not provided or null) is one day into the future

PostbackUrl

string

No

Postback when order is confirmed (the postback object includes the orderId for the confirmed order and more)

SuccessReturnUrl

string

No

A URL to redirect the buyer to when the order is confirmed by the buyer

CancelReturnUrl

string

No

A URL to redirect the buyer to when the order is cancelled by the buyer

Items

ICollection<ItemModel>

Yes

List of items, not empty. See ItemModel for details

SequenceType

enum OrderSequenceType

No

Sequence type of order. See OrderSequenceType for details

MandateId

string

No

Payment card authentication id, only applies if SequenceType is Recurring otherwise the mandateId should be null

BuyerModel

Name

Type

Required

Description

Name

Type

Required

Description

Barcode

string

No

Buyer barcode, when this is used the other buyer properties are ignored

Name

string

No

Name of the buyer

Ssn

string

No

Social security number / Identity number of the buyer (ísl. kennitala)

Email

string

No

The buyer's email address

MobileNumer

string

No

The buyer's mobile number

ItemModel

Name

Type

Required

Description

Name

Type

Required

Description

Code

string

No

Unique item code

Name

string

Yes

Name of the item

Quantity

float

No

Quantity of the given unit

Unit

string

No

The measurement

UnitPrice

decimal?

No

Price for a single unit

Amount

decimal

No

Total amount

GroupName

string

No

Optional group name

IsOptional

bool?

No

Set if the item should be optional. When this is not set, the item defaults to non-optional

IsDefaultSelected

bool?

No

Optionally make an item selected by default

OrderSequenceType

Name

Description

Name

Description

0 = OneOff

Implies that the order is, in reality, not a part of a sequence of recurring orders but rather a stand-alone order

1 = First

Implies that the order is the first in a sequence of recurring orders and will need to be manually paid for by going to the payment gateway which is the CheckoutUrl property in the response

2 = Recurring

Implies that the order is a non-first order in a sequence of recurring orders and will be automatically charged

 

SubmitOrderResult

Name

Type

Description

Name

Type

Description

OrderId

string

ID of the order

CheckoutUrl

string

URL to the payment gateway

PurchaseAccessOrderModel

Name

Type

Required

Description

Name

Type

Required

Description

MerchantId

int

Yes

Unique Pei ID for a merchant

Buyer

BuyerModel

Yes

A buyer model, cannot be null. See BuyerModel for details

Amount

decimal

Yes

Total amount

Reference

string

No

The merchant’s own reference for the order

PostbackUrl

string

No

Postback when order is confirmed (the postback object includes the orderId for the confirmed order and more)

Items

ICollection<ItemForm>

Yes

List of items, not empty. See ItemModel for details

PurchaseAccessOrderResult

Name

Type

Description

Name

Type

Description

OrderId

string

Id of the order

 

PurchaseAccess

Method

Description

Input

Output

Pei API method

Method

Description

Input

Output

Pei API method

HasAccessAsync

Check if merchant has access to purchase orders for a buyer.

merchantId, int

buyerSsn, string

bool

GET: /api/purchaseaccess

RequestAccessAsync

Request access to purchase orders for a buyer by sending a pin to the buyer.

RequestAccessModel

HttpResponseMessage

POST: /api/purchaseaccess/request

ConfirmAccessAsync

Confirm merchant access to purchase orders for the buyer with a pin from the buyer.

ConfirmAccessModel

HttpResponseMessage

POST: /api/purchaseaccess

RequestAccessModel

Name

Type

Required

Description

Name

Type

Required

Description

MerchantId

int

Yes

Pei ID of the merchant requesting access

BuyerSsn

string

Yes

Ssn of the buyer

MobileNumber

string

Yes

The mobilenumber to send the confirmation PIN to

ConfirmAccessModel

Name

Type

Required

Description

Name

Type

Required

Description

MerchantId

int

Yes

Pei ID of the merchant requesting access

BuyerSsn

string

Yes

Ssn of the buyer

Pin

string

Yes

The PIN to confirm the access

PinOrders

Method

Description

Input

Output

Pei API method

Method

Description

Input

Output

Pei API method

SendPinAsync

Send the user a PIN via SMS for a specific order.

orderId, string

HttpResponseMessage

POST: /api/orders/{orderId}/pins

PayOrderAsync

Pay a specific order by using a PIN received through SMS.

orderid, string

pin, string

HttpResponseMessage

POST: /api/orders/{orderId}/pins/pay

 

Example usage

Create a new PeiService configured for staging:

var peiService = new PeiApiConfiguration() .WithStagingAuth("democlient", "demosecret") //.WithAuth("clientId", "secret") for production .CreateService();

 

PurchaseAccess payment flow, where the buyer has not confirmed access yet:

var merchantId = 4; // test merchant var hasAccess = await peiService.PurchaseAccess.HasAccessAsync(merchantId, "buyerSsn"); //hasAccess == false var requestAccess = await peiService.PurchaseAccess.RequestAccessAsync(/*RequestAccessModel object*/); //pin sent to buyer var confirmAccess = await peiService.PurchaseAccess.ConfirmAccessAsync(/*ConfirmAccessModel object*/); //buyer confirmed, further calls to hasAccess should return true //hasAccess == true var payOrderResult = await peiService.Orders.PayOrderAsync(/*PurchaseAccessOrderModel object*/); //order created and confirmed

 

PurchaseAccess payment flow, where the buyer has confirmed access before:

//hasAccess == true var hasAccess = await peiService.PurchaseAccess.HasAccessAsync(merchantId, "buyerSsn"); var payOrderResult = await peiService.Orders.PayOrderAsync(/*PurchaseAccessOrderModel object*/); //order created and confirmed

 

PinOrders payment flow: