Skip to content

keyme/worldnet-payments

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

9 Commits
.openapi-generator
.openapi-generator
 
 
docs
docs
 
 
lib
lib
 
 
spec
spec
 
 
.gitignore
.gitignore
 
 
.openapi-generator-ignore
.openapi-generator-ignore
 
 
.rspec
.rspec
 
 
.rubocop.yml
.rubocop.yml
 
 
.travis.yml
.travis.yml
 
 
Gemfile
Gemfile
 
 
README.md
README.md
 
 
Rakefile
Rakefile
 
 
git_push.sh
git_push.sh
 
 
worldnet_payments.gemspec
worldnet_payments.gemspec
 
 

Repository files navigation

worldnet_payments

WorldnetPayments - the Ruby gem for the Merchant API

Introduction

The Merchant API enables you to connect seamlessly and securely to our Omni-Channel Payments Platform.

Our APIs are built around REST principles and OpenAPI Specification definitions. Complying to such industry standards means that we can offer developers a much better experience by exposing predictable resource-oriented URL's as well as a comprehensive range of HTTP response codes and verbs. Moreover, you have the possibility to enable and take full advantage of HATEOAS controls to provide out-of-the-box Discoverability and Functional-Awareness for your integrations.

Get started on building full-featured payment applications and join us in the Revolution of Intelligent Retail.

Authentication

The Merchant API uses a combination of API Keys and Java Web Tokens (JWT) to authenticate requests. API Key's hold all the necessary information for issuing JWT access tokens which in turn are required to access protected resources and operations. Therefore, before you can start making any calls, you must generate an API Key and use it to obtain access tokens.

Please, make yourself familiar with the following security schemes before proceeding:

Generating an API Key

The API supports two levels of authentication. Our consumers can either authenticate on a merchant level and have their API Keys limited to the scope of a specific merchant or, if you are one of our ISV (Independent Software Vendor) partners, you can have only one API Key for a whole integration which may consist of more than one merchant.

Although it is handy for ISVs to have one key that can authenticate in multiple merchant accounts, they can still use merchant-level authentication if they want to have more control and keep their merchant authentication separate. In this case, the gateway will require an extra header called X-Integration-ID - containing the integration's identifier - to be sent in every request.

How to generate Merchant-Level API Keys?

  1. Log into the SelfCare System with the credentials you received in the welcome email.
  2. Under Settings, navigate to API Keys, and then click the NEW API KEY button.
  3. Enter an alias and set the permission modes for each Sub-API.
  4. Select the terminals that you want the API Key to be allowed to operate.
  5. Back on the list, choose the action View Authentication Key to be able to see your Key's authentication token.

How to generate Integration-Level API Keys?

ISV integrations are managed by our support and integration teams. Our team will be happy to create your API Key when requested.
Once created, the authentication token is sent by email in an encrypted file and our team will guide you on how to access its content.

Note: Since ISV developers are not able to create their own keys, we recommend Merchant-Level authentication during integration and test phases as a way to speed up development and avoid the overhead of contacting members of the support team.

Obtaining an Access Token

In order to obtain an access token you must use the authenticate operation passing your API Key in the HTTP Authorization header with Basic authentication scheme.

In the snippet below we show how to achieve that using cURL. However, if you are not familiar with command line tools we recommend Postman.

curl https://testpayments.worldnettps.com/merchant/api/v1/account/authenticate \\
  -H \"Authorization: Basic <Merchant API Key>\"

For every successful request you should receive a response just like the one below containing the information associated with your credentials, such as hours to expiry and privileges. Include the JWT Token from the token property in the Authorization header with Bearer authentication scheme for following requests to prove your identity and access protected resources.

{
    \"audience\": \"testpayments.worldnettps.com\",
    \"boundTo\": \"My API Key\",
    \"tokenType\": \"Bearer\",
    \"token\": \"<JWT Access Token>\",
    \"expiresIn\": 1,
    \"enableHypermedia\": true,
    \"roles\": [],
    \"allowedTerminals\": []
}

For security reasons, access tokens expire after a certain amount of time. Therefore, your application must implement a mechanism to keep track of the expiresIn property which is the number of hours the token is valid for.

Note: The lifespan of a token must not be hard-coded on the client-side as the value of expiresIn property is subject to change without prior notice.

Making Authenticated Calls

Apart from the authenticate operation, the entire API requires Bearer authentication scheme and expects a valid JWT token as proof of identity. The cURL snippet below is an example of how to use your access token, in this specific case, to request the list of available terminals in your account.

curl https://testpayments.worldnettps.com/merchant/api/v1/account/terminals?pageSize=10 \\
  -H \"Content-Type: application/json\" \\
  -H \"Authorization: Bearer <JWT Token>\"

Note: The API will issue a response with status 401 Unauthorized for requests carrying an expired JWT.

API Requests

We provide developers looking to integrate with our solutions with a full-featured Sandbox.

In order to perform actions on the API's resources you must combine your requests with the proper HTTP Request Method.

The Merchant API supports the following HTTP Methods which are sometimes referred as HTTP Verbs:

HTTP Method Description
GET It requests a representation of the specified resource. Requests using GET are read-only.
POST It is used to submit an entity to the specified resource, often causing a change in state on the server.
PATCH It is used to apply partial modifications to a resource.
DELETE It deletes / cancels / reverts the specified resource.

Request Identifiers

The Merchant API assigns a unique identifier for every request that comes in. You can find your requests' identifiers either in the X-Request-Id header or in the Error field debugIdentifier.

Request ID's are part of an effort to speed troubleshooting by facilitating communication between clients and our support team. Since we keep track of all request identifiers in our log files, you just need to inform the request's identifier when asking us to assist you with problems that might come up during your integrations.

Customer Account Payloads

Client applications need to be able to send the customers' account details when generating payments, initiating unreferenced refunds and registering secure credentials. This information is expected in the form of payloads which varies based on the mechanism used to capture the account/card details.

For instance, when the card details are manually inputted, a KEYED payload is expected. However, an EMV payload is always expected for contact and contactless EMV transactions. It is worth mentioning that the proper use of payloads also depend on the channel over which your terminal is operating. In the table below we show the supported payloads for each of the three available channels:

Channel Supported Payloads
WEB (eCommerce) KEYED, SECURE_CREDENTIALS, DIGITAL_WALLET
POS (Cardholder Present) KEYED, EMV, RAW, MAG_STRIPE
MOTO (Mail/Telephone Order) KEYED, SECURE_CREDENTIALS

Request Headers

HTTP Header Description
Accept The response format expected by your application.
The Merchant API only produces application/json response format.
Accept-Language It advertises which languages the client is able to understand, and which locale variant is preferred.
The Merchant API fully supports English en and French fr languages.
Content-Type The body format of the request your application is sending to the API.
The Merchant API only consumes application/json content type.
Authorization It must contain the credentials (API Key or JWT Access Token) to authenticate your application.
The API will issue a 401 Unauthorized response with the WWW-Authenticate header attached if your application fails to use this header properly.
X-Integration-ID It should be sent in every call by ISV integrations that use Merchant-Level API Keys for authentication

Partial Updates

Partial update requests are signaled with the HTTP method PATCH. To perform partial updates, clients must specify only the properties that have changed.

Note: To clear the content of a property, supply an empty value.

Testing Requests

Eventually it will be necessary to perform some transactions. For resources such as testing credit cards and simulated responses, see Testing Resources.

API Responses

Client applications must be able to handle JSON body format as well as a range of HTTP status codes when processing responses. Some resources might also include contextual hypermedia links. We strongly recommend that clients use these links to request more information or perform additional actions on a given resource.

HTTP Status Codes

The Merchant API has adopted a comprehensive range of status codes where 2XX statuses are returned for successful requests and 4XX or 5XX for failed requests.

The full range of status codes supported by this API:

HTTP Status Code Description
200 OK Indicates that the request has succeeded.
201 Created Indicates that the request has succeeded and has led to the creation of a resource.
204 No Content Indicates that the server successfully executed the method but returns no response body.
This status is sent specifically to respond to DELETE requests.
400 Bad Request Indicates that the server cannot or will not process the request due to malformed request syntax or schema violation.
401 Unauthorized Indicates that the request has not been applied because it lacks valid authentication credentials.
This status is sent with a WWW-Authenticate header that contains information on how to authorize correctly.
403 Forbidden Indicates that the server understood the request but refuses to authorize it due to the lack of permissions.
Re-authenticating will make no difference until the proper permissions and terminals are added to the API Key.
404 Not Found Indicates that the server cannot find the requested resource.
405 Method Not Allowed Indicates that the request method is known by the server but is not supported by the target resource.
406 Not Acceptable Indicates that the server cannot produce a response matching the value from Accept header.
415 Unsupported Media Type Indicates that the server refuses to accept the request because the payload format described by the Content-Type is unsupported.
422 Unprocessable Entity Indicates that the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to proceed due to semantic errors or failed business validations.
500 Internal Server Error Indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
501 Not Implemented Indicates that the server does not yet support the functionality required to fulfill the request, but might in the future.

Error Handling

In the event of a failure, the Merchant API returns an error response body that includes additional details in the format below:

{
    \"debugIdentifier\": \"ae6d75eb-381b-4a01-9f49-fdff12e3848b\",
    \"details\": [
        {
            \"errorCode\": \"X_400_002\",
            \"errorMessage\": \"Unable to deserialize value\",
            \"source\": {
                \"location\": \"BODY\",
                \"resource\": \"TipType\",
                \"property\": \"type\",
                \"value\": \"VARIABLE\",
                \"expected\": \"Acceptable values: [PERCENTAGE, FIXED_AMOUNT]\"
            }
        }
    ]
}

Error messages are intended to help developers to fix any problems that may come up during integration.
However, if you ever have a hard time troubleshooting an issue or even wish to make a suggestion, do not hesitate to contact us. Do not forget to send us the debugIdentifier along with your inquiries.

HATEOAS (Hypermedia Links)

HATEOAS is a powerful mechanism when it comes to enabling self-discoverability, reducing invalid state transition calls and protecting your application against unexpected changes on resources URL's.

This snippet from a sample payments response shows the list of hypermedia controls that represent the operations available for the newly created payment resource.

\"links\": [
    {
        \"rel\": \"capture\",
        \"method\": \"PATCH\"
        \"href\": \"https://testpayments.worldnettps.com/merchant/api/v1/transaction/payments/GH2AERQEJS/capture\"
    },
    {
        \"rel\": \"refund\",
        \"method\": \"POST\"
        \"href\": \"https://testpayments.worldnettps.com/merchant/api/v1/transaction/payments/GH2AERQEJS/refunds\"
    },
    {
        \"rel\": \"update\",
        \"method\": \"PATCH\"
        \"href\": \"https://testpayments.worldnettps.com/merchant/api/v1/transaction/payments/GH2AERQEJS\"
    },
    {
        \"rel\": \"self\",
        \"method\": \"GET\"
        \"href\": \"https://testpayments.worldnettps.com/merchant/api/v1/transaction/payments/GH2AERQEJS\"
    },
    {
        \"rel\": \"reverse\",
        \"method\": \"DELETE\"
        \"href\": \"https://testpayments.worldnettps.com/merchant/api/v1/transaction/payments/GH2AERQEJS\"
    }
]

Pagination

The Merchant API features a cursor-based pagination which is sometimes referred as continuation token pagination. This pagination approach works by returning a pointer to a specific item in the dataset. On subsequent requests, the server returns results after the given pointer.

Clients don't need to worry about implementing complex pagination mechanism in their applications as we return, for all paginated resources, the total count and a hypermedia link that can be used to load more results. It is important to mention that the response containing the last elements will not contain a next hyperlink. We do that so you know that there are no more elements to load.

\"links\": [
    {
        \"rel\": \"next\",
        \"method\": \"GET\"
        \"href\": \"https://testpayments.worldnettps.com/merchant/api/v1/account/terminals?next=CWY4XRGUUY\"
    }
]

The default number of elements per page is 10 and the maximum is 100, but it can be changed by adding the query parameter pageSize to requests as follows:

curl https://testpayments.worldnettps.com/merchant/api/v1/account/terminals?pageSize=5 \\
  -H \"Content-Type: application/json\" \\
  -H \"Authorization: Bearer <JWT Token>\"

Note: For performance reasons, the elements inside of a paginated list only represent a compact version of the resource listed. To retrieve the full version of a given resource, client applications must make a subsequent request using the proper hypermedia link.

Versioning

Versioning ensures that changes are backward compatible. The Merchant API uses a major and minor version nomenclature to manage changes.

Major Versions

Major version numbers will reflect in the REST URL, for example /api/v1/transaction/payments.

Currently, v1 is the only supported major version.

Minor Versions

Minor and backward-compatible changes will be advertised via X-API-Version response header, for example X-API-Version: 2020-01-01.

Developers should use this header to keep track of new features and optimizations that might benefit their applications.

This SDK is automatically generated by the OpenAPI Generator project:

Installation

Build a gem

To build the Ruby code into a gem:

gem build worldnet_payments.gemspec

Then either install the gem locally:

gem install ./worldnet_payments-1.0.0.gem

(for development, run gem install --dev ./worldnet_payments-1.0.0.gem to install the development dependencies)

or publish the gem to a gem hosting service, e.g. RubyGems.

Finally add this to the Gemfile:

gem 'worldnet_payments', '~> 1.0.0'

Install from Git

If the Ruby gem is hosted at a git repository: https://github.com/GIT_USER_ID/GIT_REPO_ID, then add the following in the Gemfile:

gem 'worldnet_payments', :git => 'https://github.com/GIT_USER_ID/GIT_REPO_ID.git'

Include the Ruby code directly

Include the Ruby code directly using -I as follows:

ruby -Ilib script.rb

Getting Started

Please follow the installation procedure and then run the following code:

# Load the gem
require 'worldnet_payments'

# Setup authorization
WorldnetPayments.configure do |config|
  # Configure Bearer authorization (JWT): Bearer
  config.access_token = 'YOUR_BEARER_TOKEN'
end

api_instance = WorldnetPayments::CardsApi.new
balance_inquiry_request = WorldnetPayments::BalanceInquiryRequest.new({terminal: 'terminal_example', currency: 'AED', customer_account: WorldnetPayments::Payload.new({payload_type: 'payload_type_example'})}) # BalanceInquiryRequest | 

begin
  #Balance Inquiry
  result = api_instance.balance_inquiry(balance_inquiry_request)
  p result
rescue WorldnetPayments::ApiError => e
  puts "Exception when calling CardsApi->balance_inquiry: #{e}"
end

Documentation for API Endpoints

All URIs are relative to https://testpayments.worldnettps.com/merchant

Class Method HTTP request Description
WorldnetPayments::CardsApi balance_inquiry POST /api/v1/customer/cards/balance Balance Inquiry
WorldnetPayments::CredentialsApi delete_credentials DELETE /api/v1/customer/credentials/{merchantReference} Delete Credentials
WorldnetPayments::CredentialsApi get_credentials GET /api/v1/customer/credentials/{merchantReference} Get Credentials
WorldnetPayments::CredentialsApi search_credential_transactions POST /api/v1/customer/credentials/transactions Search Latest Transactions
WorldnetPayments::CredentialsApi store_credentials POST /api/v1/customer/credentials Store Credentials
WorldnetPayments::CredentialsApi update_credentials PATCH /api/v1/customer/credentials/{merchantReference} Update Credentials
WorldnetPayments::PaymentsApi capture_payment PATCH /api/v1/transaction/payments/{uniqueReference}/capture Capture a Payment
WorldnetPayments::PaymentsApi get_payment GET /api/v1/transaction/payments/{uniqueReference} Get a Payment
WorldnetPayments::PaymentsApi payment POST /api/v1/transaction/payments Make a Payment
WorldnetPayments::PaymentsApi refund_payment POST /api/v1/transaction/payments/{uniqueReference}/refunds Refund a Payment
WorldnetPayments::PaymentsApi reverse_payment PATCH /api/v1/transaction/payments/{uniqueReference}/reverse Reverse a Payment
WorldnetPayments::PaymentsApi update_payment PATCH /api/v1/transaction/payments/{uniqueReference} Update a Payment
WorldnetPayments::RefundsApi get_refund GET /api/v1/transaction/refunds/{uniqueReference} Get a Refund
WorldnetPayments::RefundsApi reverse_refund PATCH /api/v1/transaction/refunds/{uniqueReference}/reverse Reverse a Refund
WorldnetPayments::RefundsApi unreferenced_refund POST /api/v1/transaction/refunds Unreferenced Refund
WorldnetPayments::RefundsApi update_refund PATCH /api/v1/transaction/refunds/{uniqueReference} Update a Refund
WorldnetPayments::SettingsApi end_of_day PATCH /api/v1/account/terminals/{terminalNumber}/endOfDay End Of Day
WorldnetPayments::SettingsApi list_device_types GET /api/v1/account/terminals/{terminalNumber}/devices List POS Device Types
WorldnetPayments::SettingsApi list_terminals GET /api/v1/account/terminals List Terminals
WorldnetPayments::SettingsApi load_device_type GET /api/v1/account/terminals/{terminalNumber}/devices/{type} Load POS Device Type
WorldnetPayments::SettingsApi load_terminal GET /api/v1/account/terminals/{terminalNumber} Load Terminal
WorldnetPayments::SettingsApi update_terminal PATCH /api/v1/account/terminals/{terminalNumber} Update Terminal
WorldnetPayments::TokensApi authenticate GET /api/v1/account/authenticate Authenticate
WorldnetPayments::TransactionsApi search_transactions GET /api/v1/transaction/transactions Search Transactions

Documentation for Models

Documentation for Authorization

Basic

  • Type: HTTP basic authentication

Bearer

  • Type: Bearer authentication (JWT)

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

7 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 3

  •  
  •  
  •  

Languages