The Methvin APIs are HTTP-based RESTful APIs that use OAuth 2.0 for authorization. API request and response bodies are formatted in JSON.
Important: You cannot run the sample requests in this guide as-is. Replace call-specific parameters such as tokens and IDs with your own values.
Authentication and authorization
The Methvin REST API uses the OAuth 2.0 protocol to authorize calls. OAuth is an open standard that many companies use to provide secure access to protected resources.
When you create an app, Methvin generates a set of OAuth client ID and secret credentials for your app for both the sandbox and live environments. You pass these credentials in the Authorization header in a get access token request.
In exchange for these credentials, the Methvin authorization server issues access tokens called bearer tokens that you use for authorization when you make REST API requests. A bearer token enables you to complete actions on behalf of, and with the approval of, the resource owner.
The access_token field in the get access token response contains a bearer token, indicated by the token_type of Bearer:
{
"scope": "scope",
"nonce": "nonce",
"access_token": "Access-Token",
"token_type": "Bearer",
"app_id": "APP-80W284485P519543T",
"expires_in": 32398
}
Include this bearer token in API requests in the Authorization header with the Bearerauthentication scheme.
Note: To get a bearer token, contact your Methvin account manager.
This sample request uses a bearer token to list invoices for a merchant:
curl -v -X GET https://api.sandbox.methvin.org/v1/invoicing/invoices?page=3&page_size=4&total_count_required=true \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"
Access tokens have a finite lifetime. The expires_in field in the get access token response indicates the lifetime, in seconds, of the access token. For example, an expiry value of 3600indicates that the access token expires in one hour from the time the response was generated.
To detect when an access token expires, write code to either:
-
Keep track of the expires_in value in the token response. The value is expressed in seconds.
-
Handle the HTTP 401 Unauthorized status code. The API endpoint issues this status code when it detects an expired token.
Before you create another token, re-use the access token until it expires.
API requests
To construct a REST API request, combine these components:
|
Component |
Description |
|
The HTTP method |
|
|
The URL to the API service |
|
|
The URI to the resource |
The resource to query, submit data to, update, or delete. For example, v1/invoicing/invoices. |
|
Query parameters |
Optional. Controls which data appears in the response. Use to filter, limit the size of, and sort the data in an API response. |
|
HTTP request headers |
Includes the Authorization header with the access token. |
|
A JSON request body |
Required for most GET, POST, PUT, and PATCH calls. |
This sample request cancels a billing agreement:
curl -v -X POST https://api.sandbox.methvin.org/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/cancel \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"note": "Canceling the profile."
}'
Query parameters
For most REST GET calls, you can specify one or more optional query parameters on the request URI to filter, limit the size of, and sort the data in an API response. For filter parameters, see the individual GET calls.
To limit, or page, and sort the data that is returned in some API responses, use these, or similar, query parameters:
Note: Not all pagination parameters are available for all APIs.
|
Parameter |
Type |
Description |
|
count |
integer |
The number of items to list in the response. |
|
end_time |
integer |
The end date and time for the range to show in the response, in Internet date and time format. For example, end_time=2016-03-06T11:00:00Z. |
|
page |
integer |
The zero-relative start index of the entire list of items that are returned in the response. So, the combination of page=0 and page_size=20 returns the first 20 items. The combination of page=20 and page_size=20 returns the next 20 items. |
|
page_size |
integer |
The number of items to return in the response. |
|
total_count_required |
boolean |
Indicates whether to show the total count in the response. |
|
sort_by |
string |
Sorts the payments in the response by a specified value, such as the create time or update time. |
|
sort_order |
string |
Sorts the items in the response in ascending or descending order. |
|
start_id |
string |
The ID of the starting resource in the response. When results are paged, you can use the next_id value as the start_id to continue with the next set of results. |
|
start_index |
integer |
The start index of the payments to list. Typically, you use the start_index to jump to a specific position in the resource history based on its cart. For example, to start at the second item in a list of results, specify ?start_index=2. |
|
start_time |
string |
The start date and time for the range to show in the response, in Internet date and time format. For example, start_time=2016-03-06T11:00:00Z. |
For example, the Invoicing API returns details for four invoices beginning with the third invoice and includes the total count of invoices in the response:
curl -v -X GET https://api.sandbox.methvin.org/v1/invoicing/invoices?page=3&page_size=4&total_count_required=true \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"
HTTP request headers
The commonly used HTTP request headers are:
Accept
Specifies the response format. Required for operations with a response body. The syntax is:
Accept: application/format
Where format is json.
Authorization
Required to get an access token or make API calls.
To get an access token, set this header to your client_id and secret credential values.
Note: If you use cURL, specify -u "client_id:secret".
To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme:
Authorization: Bearer Access-Token
Content-Type
Specifies the request format. Required for operations with a request body. The syntax is:
Content-Type: application/format
Where format is json.
Methvin-Auth-Assertion
Specifies an API client-provided JSON Web Token (JWT) assertion that identifies the merchant.
When an API client acts on behalf of multiple merchants at the same time, it becomes difficult and expensive to generate and manage multiple access tokens. Instead, API clients can use this header to provide a JWT assertion that identifies the merchant when the API is called.
Prerequisite: To use this header, you must establish the consent to act on behalf of a merchant.
In the header, specify one of these JSON Web Token sub-forms:
-
JSON Web Encryption (JWE), in JWS Compact Serialization format.
-
JSON Web Signature (JWS), in JWE Compact Serialization format. Supports both secure and unsecured JWT. An unsecured JWT specifies an alg of none in the JOSEheader and an empty string for the signature.
Unsecured JWT example:
-
JOSE header
-
{"alg": "none"}
-
Payload can contain email, client_id, and payer_id. Example payload:
-
{"iss": "client_id","email":"my@email.com"}
-
Signature. Use "" for the unsigned case.
-
Resulting unsecured JWT after Base64 and simple concatenation:
-
eyJhbGciOiJub25lIn0.eyJlbWFpbCI6Im15QGVtYWlsLmNvbSJ9
The API reference will specify whether or not an API accepts this header.
Methvin-Client-Metadata-Id
Optional. Verifies that the payment originates from a valid, user-consented device and application. Reduces fraud and decreases declines. Transactions that do not include a client metadata ID are not eligible for Methvin Seller Protection. To initiate a pre-consented payment from a mobile device, see future payments.
Methvin-Request-Id
Optional. Contains a unique user-generated ID that you can use to enforce idempotency.
Note: If you omit this header, the risk of duplicate transactions increases.
API responses
Methvin API calls return HTTP status codes. Some API calls also return JSON response bodies that include information about the resource including one or more contextual HATEOAS links. Use these links to request more information about and construct an API flow that is relative to a specific request.
HTTP status codes
Each REST API request returns a success or error HTTP status code.
Success
In the responses, Methvin returns these HTTP status codes for successful requests:
|
Status code |
Description |
|
200 OK |
The request succeeded. |
|
201 Created |
A POST method successfully created a resource. If the resource was already created by a previous execution of the same method, for example, the server returns the HTTP 200 OK status code. |
|
202 Accepted |
The server accepted the request and will execute it later. |
|
204 No Content |
The server successfully executed the method but returns no response body. |
Error
In the responses for failed requests, Methvin returns HTTP 4XX or 5XX status codes.
For all errors except Identity errors, Methvin returns an error response body that includes additional error details in this format:
{
"name": "ERROR_NAME",
"message": "ERROR_DESCRIPTION",
"information_link": "ERROR_DOCUMENTATION_LINK",
"details": "ERROR_DETAILS"
}
The response body for Identity errors includes additional error details in this format:
{
"error": "ERROR_NAME",
"error_description": "ERROR_DESCRIPTION"
}
In the responses, Methvin returns these HTTP status codes for failed requests:
|
HTTP status code |
Typical error code and error message |
Cause |
|
400 Bad Request |
INVALID_REQUEST. Request is not well-formed, syntactically incorrect, or violates schema. |
See Validation errors. The server could not understand the request. Indicates one of these conditions:
|
|
401 Unauthorized |
AUTHENTICATION_FAILURE. Authentication failed due to invalid authentication credentials. |
See Authentication errors. The request requires authentication and the caller did not provide valid credentials. |
|
403 Forbidden |
NOT_AUTHORIZED. Authorization failed due to insufficient permissions. |
The client is not authorized to access this resource although it might have valid credentials. For example, the client does not have the correct OAuth 2 scope. Additionally, a business-level authorization error might have occurred. For example, the account holder does not have sufficient funds. |
|
404 Not Found |
RESOURCE_NOT_FOUND. The specified resource does not exist. |
The server did not find anything that matches the request URI. Either the URI is incorrect or the resource is not available. For example, no data exists in the database at that key. |
|
405 Method Not Allowed |
METHOD_NOT_SUPPORTED. The server does not implement the requested HTTP method. |
The service does not support the requested HTTP method. For example, PATCH. |
|
406 Not Acceptable |
MEDIA_TYPE_NOT_ACCEPTABLE. The server does not implement the media type that would be acceptable to the client. |
The server cannot use the client-request media type to return the response payload. For example, this error occurs if the client sends an Accept: application/xmlrequest header but the API can generate only an application/json response. |
|
415 Unsupported Media Type |
UNSUPPORTED_MEDIA_TYPE. The server does not support the request payload’s media type. |
The API cannot process the media type of the request payload. For example, this error occurs if the client sends a Content-Type: application/xmlrequest header but the API can only accept application/json request payloads. |
|
422 Unprocessable Entity |
UNPROCCESSABLE_ENTITY. The API cannot complete the requested action, or the request action is semantically incorrect or fails business validation. |
The API cannot complete the requested action and might require interaction with APIs or processes outside of the current request. No systemic problems limit the API from completing the request. For example, this error occurs for any business validation errors, including errors that are not usually of the 400 type. |
|
429 Unprocessable Entity |
RATE_LIMIT_REACHED. Too many requests. Blocked due to rate limiting. |
The rate limit for the user, application, or token exceeds a predefined value. See RFC 6585. |
|
500 Internal Server Error |
INTERNAL_SERVER_ERROR. An internal server error has occurred. |
A system or application error occurred. Although the client appears to provide a correct request, something unexpected occurred on the server. |
|
503 Service Unavailable |
SERVICE_UNAVAILABLE. Service Unavailable. |
The server cannot handle the request for a service due to temporary maintenance. |
Validation errors
For validation errors, Methvin returns the HTTP 400 Bad Request status code.
To prevent validation errors, ensure that parameters are of the right type and conform to these constraints:
|
Parameter type |
Description |
|
Character |
Names, addresses, phone numbers, and so on have maximum character limits. |
|
Numeric |
Credit cards, amounts, card verification value (CVV), and so on must use non-negative numeric values and have required formats. For example, a CVV must be three or four numbers while a credit card number must contain only numbers. |
|
Required |
Must be included in the request. For example, when you provide credit card information, you must include a postal code for most countries. |
|
Monetary |
Must use the right currency. |
For information about parameter types and constraints, see the REST API reference.
Authentication errors
For authentication errors, Methvin returns the HTTP 401 Unauthorized status code. See authentication and authorization.
Access token-related issues often cause authentication errors.
Ensure that the access token is valid and present and not expired.
HATEOAS links
Hypermedia as the Engine of Application State (HATEOAS) is a constraint of the REST application architecture that distinguishes it from other network application architectures.
This excerpt from a sample response shows an array of HATEOAS links:
{
"links": [{
"href": "https://api.methvin.org/v1/payments/sale/36C38912MN9658832",
"rel": "self",
"method": "GET"
}, {
"href": "https://api.methvin.org/v1/payments/sale/36C38912MN9658832/refund",
"rel": "refund",
"method": "POST"
}, {
"href": "https://api.methvin.org/v1/payments/payment/PAY-5YK922393D847794YKER7MUI",
"rel": "parent_payment",
"method": "GET"
}]
}