vipps-ecom-api-checklist.md

Vipps eCommerce API Checklist

API version: 2.0.

Document version 2.1.5.

Checklist

• Integrate all the API endpoints:
  • Initiate POST:/ecomm/v2/payments
  • Capture POST:/ecomm/v2/payments/{orderId}/capture
  • Cancel PUT:/ecomm/v2/payments/{orderId}/cancel
  • Refund POST:/ecomm/v2/payments/{orderId}/refund
  • Details GET:/ecomm/v2/payments/{orderId}/details
  • For examples of requests and responses, see the Postman collection in tools.
• Send the HTTP headers in all API requests for better tracking and troubleshooting (mandatory for partners and platforms):
  • Vipps-System-Name
  • Vipps-System-Version
  • Vipps-System-Plugin-Name
  • Vipps-System-Plugin-Version
• Follow the orderId recommendations.
• Correctly handle callbacks from Vipps, both for successful and unsuccessful payments. See the API documentation for how callback URLs are built, make test calls to make sure you handle the POST requests correctly. Vipps does not have capacity to manually do this for you.
  • Callback POST:[callbackPrefix]/v2/payments/{orderId}
  • For Vipps Hurtigkasse (express checkout) only:
    • Shipping details POST:[shippingDetailsPrefix]/v2/payments/{orderId}/shippingDetails
    • Remove consent DELETE:[consetRemovalPrefix]/v2/consents/{userId}
• Avoid Integration pitfalls
  • The Merchant must not rely on fallback or callback alone, and must poll GET:/ecomm/v2/payments/{orderId}/details as documented (this is part of the first item in this checklist, but it's still a common error).
  • The merchant must handle that the fallback URL is opened in the default browser on the phone, and not in a specific browser, in a specific tab, in an embedded browser, requiring a session token, etc. See the API guide: Recommendations regarding handling redirects. See the FAQ: How can I open the fallback URL in a specific (embedded) browser?
  • The Vipps branding must be according to the Vipps design guidelines.

Flow to go live for direct integrations

1. The merchant orders Vipps på Nett.
2. Vipps completes customer control (KYC, PEP, AML, etc).
3. The merchant receives an email from Vipps saying that they can log in with bankID on portal.vipps.no and retrieve API keys.
4. The merchant completes all checklist items above. Please double check to avoid mistakes.
5. The merchant verifies the integration in the test environment by checking that there are test IDs (orderId) in the Vipps test environment, with the following states:
   • A complete order ending in REFUND (/refund request).
   • A complete order ending in VOID (/cancel request).
   • In the test environment this must be verified using the API itself.
6. The Merchant verifies the integration in the production environment (similar to step 5):
   • A complete order ending in REFUND (/refund request).
   • For reserve capture: A complete order ending in VOID (/cancel request after reserve).
   • We recommend checking this using both the API itself and the API Dashboard available under "Utvikler" on portal.vipps.no.
   • Please note: Vipps does not do any kind of activation or make any changes based on this checklist. The API keys for the production environment are made available on portal.vipps.no as soon as the customer control (see step 2) is completed, independently of this checklist.
7. The Merchant goes live 🎉

Flow to go live for direct integrations for partners

See: Vipps partners.

Questions?

We're always happy to help with code or other questions you might have! Please create an issue, a pull request, or contact us.

Sign up for our Technical newsletter for developers.