Netgiro API - checkout

Testing url (with swagger documentation): https://test.netgiro.is/api/checkout

Production url: https://api.netgiro.is/v1

More info for testing process (test provider AppId and SecretKey, test user credentials etc.) can be found here

Also, example application can be found at https://demoshop.netgiro.is/ with source code here

For any questions and concerns about API integration, please contact this mail: dev@netgiro.is

Online checkout (webshop)

Details

Chronology

1. Provider calls InsertCart (specifies ConfirmationType and CustomerId)
2. Customer confirms cart *
3. Provider confirms cart **
• If ConfirmationType = Automatic => Cart is confirmed automatically on server and provider just calls CheckCart periodically to check status of cart
• If ConfirmationType = Manual => Provider calls ConfirmCart
• If ConfirmationType = ServerCallback => Provider gets callback from server that cart is confirmed

* Customer can confirm cart in 1 way (CustomerId param on InsertCart):

• If provider entered GSM as CustomerId
• Customer gets push notification where he can accept/reject payment request (if customer doesn't have Netgiro mobile app he gets SMS to install it)

** Provider can confirm cart in 3 ways (ConfirmationType param on InsertCart):

• If provider specified ServerCallback as ConfirmationType (CallbackUrl has to be specified)
• Provider gets callback from server that payment is created
• Provider doesn't need to confirm cart, just calls CheckCart periodically and checks if payment is created (or canceled if customer rejected)

• If provider specified Automatic as ConfirmationType
• Provider gets callback from server that payment is created
• Server automatically creates payment after customer confirmation
• Provider doesn't need to confirm cart, just calls CheckCart periodically and checks if payment is created (or canceled if customer rejected)

• If provider specified Manual as ConfirmationType
• Server creates reservation after customer confirmation
• Provider calls CheckCart periodically and checks if reservation is created (or canceled if customer rejected)
• When CheckCart returns that reservation is created, provider needs to call ConfirmCart to create payment

Process flow

GSM confirmation

Offline checkout (POS)

Details

Chronology

1. Provider calls InsertCart (specifies ConfirmationType and CustomerId)
2. Customer confirms cart *
3. Provider confirms cart **
• If ConfirmationType = Automatic => Cart is confirmed automatically on server and provider just calls CheckCart periodically to check status of cart
• If ConfirmationType = Manual => Provider calls ConfirmCart
• If ConfirmationType = ServerCallback => Provider gets callback from server that cart is confirmed

* Customer can confirm cart in 3 ways (CustomerId param on InsertCart):

• If provider entered GSM as CustomerId
• Customer gets push notification where he can accept/reject payment request (if customer doesn't have Netgiro mobile app he gets SMS to install it)
• If provider entered SSN as CustomerId
• Customer gets SMS with payment code (customer reads it from SMS message) and provider enters payment code into POS and calls ConfirmCart
• If provider entered AppCode (customer reads it from mobile app) as CustomerId
• Provider calls ConfirmCart

** Provider can confirm cart in 3 ways (ConfirmationType param on InsertCart):

• If provider specified ServerCallback as ConfirmationType (CallbackUrl has to be specified)
• Provider gets callback from server that payment is created
• Provider doesn't need to confirm cart, just calls CheckCart periodically and checks if payment is created (or canceled if customer rejected)

• If provider specified Automatic as ConfirmationType
• Provider gets callback from server that payment is created
• Server automatically creates payment after customer confirmation
• Provider doesn't need to confirm cart, just calls CheckCart periodically and checks if payment is created (or canceled if customer rejected)

• If provider specified Manual as ConfirmationType
• Server creates reservation after customer confirmation
• Provider calls CheckCart periodically and checks if reservation is created (or canceled if customer rejected)
• When CheckCart returns that reservation is created, provider needs to call ConfirmCart to create payment

Process flow

AppCode confirmation

SSN confirmation

GSM confirmation

Result codes

In addition to the normal result codes (200, 400, etc.), custom codes have been introduced that provide a detailed explanation of the situation that occurred during payment. They are listed below:

Code	Explanation
10200	Payment completed
10201	Payment canceled
10202	Payment already canceled
10203	Payment already confirmed
10302	Customer declined payment
10304	Cart not valid
10305	Minimum amount error
10306	Customer does not exist
10307	Customer declined payment
10422	Customer declined payment
10423	Customer declined payment
10424	Cart not found
10425	Pending customer payment confirmation (to confirm payment request in mobile app)
10426	Reservation created and waiting for provider confirmation (when ConfirmationType = Manual, provider needs to call ConfirmCart)
10427	Confirmation type not valid (when calling InsertCart)
10428	Additional confirmation needed (in cases when after SSN, provider needs to enter SMS code from customer)
10429	Reservation created and waiting for provider callback response (when ConfirmationType = ServerCallback)

InsertCart

https://test.netgiro.is/api/checkout/InsertCart

Creates and inserts cart

Request body:

Name	Required	Description
Amount	Yes	Total amount of the purchase
Reference	Yes	Reference
CustomerId*	Yes	SSN, SMS code, AppCode or GSM number for client identification
ConfirmationType**	Yes	Provider’s way of confirming purchases after customer confirmation
CallbackUrl***	No	Url to which will be made post request after customer has confirmed the sale
Description	No	Purchase description
CartItemRequests	No	Cart items

*SSN for testing is 1111111119, GSM for testing is 7700001, AppCode can be generated here at the bottom of page

**Confirmation type values: 0 - automatic, 1 - server callback, 2 - manual

***If you provide CallbackUrl on InsertCart:

• Callback on that url will be received when customer confirms payment request in mobile app
• Callback won’t be received if customer cancelled, but CheckCart will check that cart is canceled
  
  

Response body:

Name	Values
Success	true, false
ResultCode	see ResultCodes section
TransactionId	GUID (cart identifier used later for checking or canceling cart)
ProcessCartCheckIntervalMiliseconds	int? (The pace how often the cart should be checked by provider)

Possible responses for InsertCart:

• Successful insert
  • Success = true
  • ResultCode = Success (200)
  • TransactionId = GUID
• Not a customer or any other validation error
  • Success = false
  • ResultCode = GenericError (400) or any other error code

After you create cart with CustomerId = 7700001 (GSM number as CustomerId) you can simulate customer confirmation or rejection (as in mobile app) on https://test.netgiro.is/customer/. See explanation here.

CheckCart

https://test.netgiro.is/api/checkout/CheckCart

This method needs to be called periodically to check status of cart when customer confirms/rejects cart.

• If ConfirmationType = Automatic or ServerCallback, this method just tells provider that payment is created.
• If ConfirmationType = Manual, this method tells provider that customer confirmed cart and after that provider needs to confirm it by calling ConfirmCart.

Request body:

Name	Required	Description
TransactionId	Yes	Cart identifier

Response body:

Name	Values
Success	true, false
PaymentSuccessful	true, false (describes if cart is confirmed by customer)
ResultCode	see ResultCodes section
PaymentInfo	object with data about payment

PayementInfo body:

Name	Values
TransactionId	Identifier of the payment in Netgíró system
InvoiceNumber	Invoice number for the payment
ReferenceNumber	Reference number parameter from the request, identifying the order in the providers system
StatusId	Status of payment: 1 - unconfirmed, 2 - confirmed, 5 - canceled
Created	Time when payment was created
TotalAmount	Amount of payment

Possible responses for CheckCart:

• Payment created
  • Success = true
  • PaymentSuccessful = TRUE
  • ResultCode = PaymentConfirmed (10200)
• Cart canceled or doesn’t exist, etc.
  • Success = true
  • PaymentSuccessful = false
  • ResultCode = PaymentCanceled (10201)
• Cart active, waiting for customer confirm or reject
  • Success = true
  • PaymentSuccessful = false
  • ResultCode = PendingCustomerConfirmation (10425)
• Cart confirmed by customer, reservation created and provider needs to confirm purchase by calling ConfirmCart -> this is only for cases where provider sends ConfirmationType = Manual on InsertCart
  • Success = true
  • PaymentSuccessful = false

  • ResultCode = ReservationCreatedAndWaitingForProviderConfirm (10426)

  • Cart active, additional confirmation needed (in cases where SMS code needs to be inserted after SSN to confirm cart)
    • Success = true
    • PaymentSuccessful = false
    • ResultCode = AdditionalConfirmationNeeded (10428)
• Cart confirmed by customer, reservation created and provider needs to confirm purchase by sending callback -> this is only for cases where provider sends ConfirmationType = ServerCallback on InsertCart
  • Success = true
  • PaymentSuccessful = false
  • ResultCode = ReservationCreatedAndWaitingForProviderCallback (10429)
    

ConfirmCart

https://test.netgiro.is/api/checkout/ConfirmCart

Confirms cart from provider side if ConfirmationType = Manual.

Request body:

Name	Required	Description
TransactionId	Yes	Cart identifier
Identifier	No	Customer identifier(SSN, app code, phone number)

Response body:

Name	Values
Success	true, false
PaymentSuccessful	true, false
ResultCode	see ResultCodes section
PaymentInfo	object with data about payment

PayementInfo body:

Name	Values
TransactionId	Identifier of the payment in Netgíró system
InvoiceNumber	Invoice number for the payment
ReferenceNumber	Reference number parameter from the request, identifying the order in the providers system
StatusId	Status of payment: 1 - unconfirmed, 2 - confirmed, 5 - canceled
Created	Time when payment was created
TotalAmount	Amount of payment

Possible responses for ConfirmCart:

• Payment failed
  • Success = true
  • PaymentSuccessful = false
  • ResultCode = 400 or some error other code
• Payment created
  • Success = true
  • PaymentSuccessful = true
  • ResultCode = PaymentConfirmed (10200)
    

CancelCart

https://test.netgiro.is/api/checkout/CancelCart

Cancels cart (if customer hasn’t already confirmed it). If customer already confirmed cart it can’t be canceled from provider side.

Request body:

Name	Required	Description
TransactionId	Yes	Cart identifier

Response body:

Name	Values
Success	true, false
ResultCode	see ResultCodes section
PaymentInfo	object with data about payment

PayementInfo body:

Name	Values
TransactionId	Identifier of the payment in Netgíró system
InvoiceNumber	Invoice number for the payment
ReferenceNumber	Reference number parameter from the request, identifying the order in the providers system
StatusId	Status of payment: 1 - unconfirmed, 2 - confirmed, 5 - canceled
Created	Time when payment was created
TotalAmount	Amount of payment

Possible responses for CancelCart:

• Customer confirms before provider cancel (payment exists, can’t be canceled)
  • Success = false
  • ResultCode = PaymentConfirmed (10200)
• Provider cancels on time
  • Success = true
  • ResultCode = PaymentCanceled (10201)