Link Search Menu Expand Document

Netgiro API - checkout

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

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

ng-checkout-flow-gsm

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

ng-checkout-flow-gsm

SSN confirmation

ng-checkout-flow-gsm

GSM confirmation

ng-checkout-flow-gsm

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 is blacklisted
10304 Cart not valid
10305 Minimum amount error
10306 Customer does not exist
10307 Customer not verified
10422 Customer inactive
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

*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)

© 2019 Netgíró hf. - Kt: 6812122050 | Borgartúni 27, 105 Reykjavík | Sími: 4 300 330 | netgiro@netgiro.is