NAV
shell

Introduction

Welcome to the MYMOID API!

We define how MYMOID’s payment API works throughout this section. This documentation is directed to the development departments of businesses that want to integrate with it. Therefore, it has a technical nature.

This guide assumes that your company has been previously registered and that it has the necessary credentials to be able to interact with the payment API. MYMOID’s API consists of an API REST with a series of services secured by unique credentials assigned to each business.

Our main concepts are based on the next three entities: Payment Order, Payment Method and Payment. Within the platform these entities interact with each other to carry out the payment process and store the information about it.

The entire API is based on the concept of a Payment Order. This Payment Order reflects a payment and the interaction between a business and a client. As such, this document makes constant references to this term, which is defined in more detail in the corresponding section.

Environments

MYMOID’s API has two environments: Sandbox and Production.

MYMOID Environments

Sandbox environment

The Sandbox environment is dedicated to integration trials for new companies.

In this environment, there is no real movement of money and all the tests are performed with a testing card and actual payment cards cannot be entered as it will not work. The configuration data of this environment are:

mymoidServerUrl: https://sandbox.mymoid.com

The testing card available to operate in this environment is the following:

Field Value
Cardholder any
Card number 4548812049400004
Expiration date 12/20
CVV 123

Production environment

The Production environment is the real environment. All the operations in this environment are valid and it only accepts actual cards. The configuration data of this environment are:

mymoidServerUrl: https://api.mymoid.com

Application

When you create a new merchant in our platform, an application is the entity responsible for storing the credentials and permissions for the merchant. These applications make different credentials with each other that can be configured with special permissions to perform certain types of operations.

Permissions

Name Description
GENERATION Generate and consult the application Payment Orders.
PAY Pay, refund and cancel the application Payment Orders.
REUSE Reuse the application already paid Payment Orders.
MASTER This permission contain all the permissions listed before and also can operate over all the Payment Orders created for the merchant.

Authentication

All not public API calls must have a specific HTTP header in all their requests in order to be able to identify and validate the application of the business which performs the calls. The header which must be used is the enabled ‘Authorization’, which by definition, can authenticate the requests received. The content that the header must carry is composed this way:

'Basic ' + Base64( APP_ID + ':' + APP_SECRET)

Where the APP_ID (Application ID) is the unique identifier of the Application and APP_SECRET (Application Secret Key) is the secret key for the same application. MYMOID expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Basic Base64Value

Example

In first place, the APP_ID must be linked, followed by the symbol ’:’ to the APP_SECRET. We will convert this to Base64 and we will link the result later to the 'Basic’ text (between the word Basic and the calculated Base64 there will be a blank space). We can see how to compose it with the following example data:

APP_ID: 5f93015589fcea018f0c2d97bd0a3508186a8b7d360591b0547d0743de2fe284

APP_SECRET: 97158fbb7852bfa0661033650a721ff7b97a3c1a0d41aafaa680b6f68c786196

Base64 calculated using above APP_ID and SECRET_KEY:

NWY5MzAxNTU4OWZjZWEwMThmMGMyZDk3YmQwYTM1MDgxODZhOGI3ZDM2MDU5MWIwNTQ3ZDA3NDNkZTJmZTI4NDo5NzE1OGZiYjc4NTJiZmEwNjYxMDMzNjUwYTcyMWZmN2I5N2EzYzFhMGQ0MWFhZmFhNjgwYjZmNjhjNzg2MTk2

Then the authorization header for the example credentials will be:

Basic NWY5MzAxNTU4OWZjZWEwMThmMGMyZDk3YmQwYTM1MDgxODZhOGI3ZDM2MDU5MWIwNTQ3ZDA3NDNkZTJmZTI4NDo5NzE1OGZiYjc4NTJiZmEwNjYxMDMzNjUwYTcyMWZmN2I5N2EzYzFhMGQ0MWFhZmFhNjgwYjZmNjhjNzg2MTk2

Payment order

In order to make a Payment, we first need to create a Payment Order. After creating a Payment Order we can interact with it to perform different types of transactions such as consultation, execution, cancellation or refund.

This payment order has two diferent types, this types would decide the flow in the payment. The follow workflows will explain the diference between this two payment types.

Standard payment Workflow

Preauthorization payment Workflow

Payment Order statuses

Status Description
AVAILABLE The initial status of a Payment Order after it has been created. This Payment Order can be expired, canceled or paid.
EXPIRED A Payment Order is expired if the expiry period (24 hours by default) has passed and the payment on it has not been made. Once the Payment Order has expired it cannot be paid.
CANCELLED A Payment Order with AVAILABLE status may be cancelled. After we cancelled the Payment Order it cannot be paid.
PREAUTH When you Preauthorize a payment order, you are effectively ring-fencing funds in your customer’s bank account in order to confirm the payment later. A Payment Order can only arrive to this status from AVAILABLE.
PAID Only after we confirm or excecute a Payment the Payment Order status would be PAID.
PARTIALLY_REFUNDED A Payment Order is in this status if we make a refund for an amount less than the total after having been paid.
REFUNDED The amount associated to the Payment Order which was previously paid has been completely refunded. To be able to proceed to a refund, the Payment Order must be in PAID or PARTIALLY_REFUNDED status.

Payment Order attributes

Attribute Description
currencyCode The type of currency associated to the payment order.
reference Payment Order’s reference.
concept Payment Order’s concept.
amount Payment Order’s amount. This should be an integer value (decimals are not accepted) and represents the value in cents. To order a 1 EUR payment order (or any other currency) the value must be 100.
payType Payment Order’s type. The right value for execute a traditional payment should be entered is PAY. But In order to use the preauthorizations you should use ‘PREAUTH’ as a payment order type.
status Payment Order’s status (detailed in the payment order section).
paymentOrderId Payment Order’s identifier.
shortCode Payment Order’s short identifier.
merchantId Merchant’s identifier that generate the order.
numericCode Payment Order’s numeric identifier. Please refer to the Generate numeric code section to learn how to generate this code.

Preauthorization attributtes

Attribute Description
paymentId Payment identifier.
operationDate Execution date.
amount Transaction’s value.
currency Transaction’s currency.
processorName Gateway processor name.
entityProcessorCode Gateway merchant code.
authorizationCode Gateway athorization code.
transactionCode Gateway transaction unique identifier.
paymentOperationType Transaction Type.

Payment attributtes

Attribute Description
paymentId Payment identifier.
operationDate Execution date.
amount Transaction’s value.
currency Transaction’s currency.
processorName Gateway processor name.
entityProcessorCode Gateway merchant code.
authorizationCode Gateway athorization code.
transactionCode Gateway transaction unique identifier.
paymentOperationType Transaction Type.

Refund attributtes

Attribute Description
paymentId Identifier of the Payment corresponding to the refund. Once you execute a refund a new Payment entity with negative value is created. This new Payment is related to the initial Payment Order.
operationDate Execution date.
amount Value of the Refund. This amount would be negative in order to represent the Payment Refund.
paymentOperationType Transaction Type.

Creating a Payment Order

Example Standard body:

{
  "currency": "EUR",
  "concept": "Oxford Shoes - Spanish Leather",
  "reference": "OXF-3479",
  "amount": 18400,
  "payType": "PAY",
  "expirationDate":"2017-11-29 12:26:00"
}

Example Preauthorization body:

{
  "currency": "EUR",
  "concept": "Oxford Shoes - Spanish Leather",
  "reference": "OXF-3479",
  "amount": 18400,
  "payType": "PREAUTH",
  "expirationDate":"2017-11-29 12:26:00"
}

Response by the API:

{
  "status": true,
  "code": 0,
  "data": {
    "paymentOrderId": "2e0d250097047b7abf1528fd271dd08cb8bc7b3fb7f51e37b3c8fc5c1eb19ec8",
    "shortCode": "JZ3PLK",
    "currencyCode": "EUR",
    "amount": 18400,
    "merchantId": "282682dd6b19c81ee7d6b3322505ebe20e03467c0a6dac129c2206e5202ba375",
    "concept": "Oxford Shoes - Spanish Leather",
    "reference": "OXF-3479",
    "status": "AVAILABLE",
    "creationDate": 1454490217151
  }
}

After defining Payment Order and the different statuses for Payment Orders, we will see how we can create one through the API. To do so, we must make the following request:

POST {mymoidServerUrl}/views/button/order

You can find API request and response examples aside.

As of this moment, all the operations that we want to make on the payment orders that we have created we will have to indicate the paymentOrderId received at the moment of creating a payment order. This unique, 64-character ID will allow us to indicate at all times which payment order we are working with. It is also important to remember the value returned in the shortCode key. This unique identifier also represents a payment order and we will need it when loading the payment form that we will discuss later.

Checking the status of a Payment Order

Response by the API:

{
  "status": true,
  "code": 0,
  "data": {
    "paymentOrderId": "2e0d250097047b7abf1528fd271dd08cb8bc7b3fb7f51e37b3c8fc5c1eb19ec8",
    "shortCode": "JZ3PLK",
    "currencyCode": "EUR",
    "amount": 18400,
    "merchantId": "282682dd6b19c81ee7d6b3322505ebe20e03467c0a6dac129c2206e5202ba375",
    "concept": "Oxford Shoes - Spanish Leather",
    "reference": "OXF-3479",
    "status": "AVAILABLE",
    "creationDate": 1454490217151
  }
}

Once a Payment order has been created, we can consult its status at any time. This request provides us the up-to-date information associated with the received Payment Order as a parameter. To do so, we have to perform the following call to the API:

GET {mymoidServerUrl}/pay/order/{paymentOrderId}

The paymentOrderId is the Payment Order identifier that we want to consult. You can see the response from the API to this request aside.

If the Payment Order is in the PAID status, we can see two fields that will be useful for you: pan, holder name and expirationCard. The pan reflects the last four digits of the card used to make the Payment, expirationCard shows its expiration date while the holder name will reflect the holder name used by the customer in the transaction.

Cancelling a Payment Order

Response by the API:

{
  "status": true,
  "code": 0,
  "data": {
    "paymentOrderId": "2e0d250097047b7abf1528fd271dd08cb8bc7b3fb7f51e37b3c8fc5c1eb19ec8",
    "shortCode": "JZ3PLK",
    "currencyCode": "EUR",
    "amount": 18400,
    "merchantId": "282682dd6b19c81ee7d6b3322505ebe20e03467c0a6dac129c2206e5202ba375",
    "concept": "Oxford Shoes - Spanish Leather",
    "reference": "OXF-3479",
    "status": "CANCELLED",
    "creationDate": 1454490217151
  }
}

After creating a Payment Order, we have the possibility to cancel it whenever it is in AVAILABLE status and it has not passed its expiry period. After cancelling the Payment Order we will not be able to perform any other action with it, and therefore we cannot proceed to Payment. In order to cancel a Payment Order, the following request must be performed:

PUT {mymoidServerUrl}/pay/order/cancel/{paymentOrderId}

You can find API response aside.

Executing a Payment Order

Example body:

{
  "expirationDate": "2022-07-01",
  "creditCardType": "VISA",
  "cardNumber": "4548810000000003",
  "cvv": "052",
  "holderName": "John Doe",
  "type": "CREDIT_CARD"
}

OK response by the API:

{
  "status": true,
  "code": 0,
  "data": {
    "paymentOrderId": "2e0d250097047b7abf1528fd271dd08cb8bc7b3fb7f51e37b3c8fc5c1eb19ec8",
    "shortCode": "JZ3PLK",
    "currencyCode": "EUR",
    "amount": 18400,
    "merchantId": "282682dd6b19c81ee7d6b3322505ebe20e03467c0a6dac129c2206e5202ba375",
    "concept": "Oxford Shoes - Spanish Leather",
    "reference": "OXF-3479",
    "status": "PAID",
    "expirationCard": "02/20",
    "holderName": "John Doe",
    "pan": "454881XXXXXX0003",
    "cardLink": "https://sandbox.mymoid.com/pay/cards/260f7a2306c5e5ec4e47d7ceb7ae39eb5adf77b9c03232bb04caed8d44b9c880",
    "creationDate": 1454490217151
  }
}

Through the following request we can execute a Payment Order:

{mymoidServerUrl}/pay/order/execute/{paymentOrderId}/anonymous

In case of not fulfilling the certification required for this transaction MYMOID provides a Payment Form with which the orders can be executed, please, refer to Payment form documentation to know more about it.

Unauthorize a Preauthorization (Preauthorization Only)

To release the previous reserved (authorized) funds it is necessary to execute a cancellation of the payment order, this will return the funds automatically and cancel the payment order.

In order to view payment order cancelation, please, refer to Cancelling a Payment Order documentation.

Confirming a Preauthorization (Preauthorization Only)

After you reserve the funds on the client’s bank account, you should confirm this transaction in order to make it effective (The funds reserved against the client’s bank account will be charged and will be travelling to your merchant account).

Partially Confirm

Response by the API:

{
  "status": true,
  "code": 0,
  "data": {
      "paymentOrderId": "b562f9b396085544d958f03e930122250ea0ad42c100860d6fcb86404368a616",
      "shortCode": "PQ2LMH",
      "currencyCode": "EUR",
      "amount": 18400,
      "merchantId": "a63c1c35c746c7be262fa971a80466b1543c7eed39b17eab2256a1b4214522c3",
      "reference": "OXF-3479",
      "concept": "Oxford Shoes - Spanish Leather",
      "status": "PAID",
      "currentStatus": {},
      "expirationCard": "02/20",
      "holderName": "John Doe",
      "pan": "454881XXXXXX0003",
      "cardLink": "https://sandbox.mymoid.com/pay/cards/260f7a2306c5e5ec4e47d7ceb7ae39eb5adf77b9c03232bb04caed8d44b9c880",
      "creationDate": 1572949974000,
      "expirationDate": 1573036374000,
      "updateDate": 1572949996063,
      "merchant": {
          "firmName": "TECHNOactivity S.L",
          "imageId": "image"
      }
  }
}

As we explain before, once a Payment order has been preauthorized, we can confirm a partiall amount from the reserved founds using the next request:

{mymoidServerUrl}/pay/order/confirm/{paymentOrderId}/{amountToConfirm}

Confirm

Response by the API:

{
  "status": true,
  "code": 0,
  "data": {
      "paymentOrderId": "b562f9b396085544d958f03e930122250ea0ad42c100860d6fcb86404368a616",
      "shortCode": "PQ2LMH",
      "currencyCode": "EUR",
      "amount": 18400,
      "merchantId": "a63c1c35c746c7be262fa971a80466b1543c7eed39b17eab2256a1b4214522c3",
      "reference": "OXF-3479",
      "concept": "Oxford Shoes - Spanish Leather",
      "status": "PAID",
      "currentStatus": {},
      "expirationCard": "02/20",
      "holderName": "John Doe",
      "pan": "454881XXXXXX0003",
      "cardLink": "https://sandbox.mymoid.com/pay/cards/260f7a2306c5e5ec4e47d7ceb7ae39eb5adf77b9c03232bb04caed8d44b9c880",
      "creationDate": 1572949974000,
      "expirationDate": 1573036374000,
      "updateDate": 1572949996063,
      "merchant": {
          "firmName": "TECHNOactivity S.L",
          "imageId": "image"
      }
  }
}

In order to confirm the full amount of the preauthorization, you can use the following request:

{mymoidServerUrl}/pay/order/confirm/{paymentOrderId}

Refunding a Payment Order

As we explain in the Payment Order Section when we have a Payment Order in PAID status, we can make a refund. There are two different kind of refunds explained below:

a) Partial refund

Partial refund - Response by the API:

{
  "status": true,
  "code": 0,
  "data": {
    "paymentOrderId": "2e0d250097047b7abf1528fd271dd08cb8bc7b3fb7f51e37b3c8fc5c1eb19ec8",
    "shortCode": "JZ3PLK",
    "currencyCode": "EUR",
    "amount": 18400,
    "merchantId": "282682dd6b19c81ee7d6b3322505ebe20e03467c0a6dac129c2206e5202ba375",
    "concept": "Oxford Shoes - Spanish Leather",
    "reference": "OXF-3479",
    "status": "PARTIALLY_REFUNDED",
    "creationDate": 1454490217151
  }

With the partial refund we have the possibility of refunding an amount less than the amount associated with the Payment Order and make multiple refunds, whenever the refunded amount in total is less than or equal to the total amount of the Payment Order.

In this case we indicate the amount to refund. If the amount to refund is equal to the total amount of the payment order, the partial refund would be equal to the total refund.

Url of the request:

PUT {mymoidServerUrl}/pay/order/refund/{paymentOrderId}/amount/{amount}

b) Total Refund

Total refund - Response by the API:

{
  "status": true,
  "code": 0,
  "data": {
    "paymentOrderId": "2e0d250097047b7abf1528fd271dd08cb8bc7b3fb7f51e37b3c8fc5c1eb19ec8",
    "shortCode": "JZ3PLK",
    "currencyCode": "EUR",
    "amount": 18400,
    "merchantId": "282682dd6b19c81ee7d6b3322505ebe20e03467c0a6dac129c2206e5202ba375",
    "concept": "Oxford Shoes - Spanish Leather",
    "reference": "OXF-3479",
    "status": "REFUNDED",
    "creationDate": 1454490217151
  }
}

Total refund refunds the entire amount paid in a single request. The advantage of this refund is that we do not need to know the amount paid initially, as we refund the total amount at one time.

Url of the request:

PUT {mymoidServerUrl}/pay/order/refund/{paymentOrderId}

You can see examples for both types of refunds aside.

Payment Order Receipt

Response by the API:

{
  "status": true,
  "code": 0,
  "data": {
    "paymentOrderId": "3e6876520916376713b4e44e6b0d33617b6281ff9728c1e3af783e2142ea96ed",
    "shortCode": "K3LZGL",
    "concept": "Oxford Shoes - Spanish Leather",
    "creationDate": "2017-11-28T09:10:39+00:00",
    "state": "PARTIALLY_REFUNDED",
    "merchant": {
      "vatNumber": "51551259w",
      "name": "Francisco Vallejo",
      "merchantId": "a63c1c35c746c7be262fa971a80466b1543c7eed39b17eab2256a1b4214522c3"
    },
    "preauthorization": {
      "preauthId": "ddac9dadfc43255fb12e447006d52a4d4209f79a79c3b497153293f61b12b9d7",
      "operationDate": "2017-11-28T09:12:48+00:00",
      "amount": 18400,
      "currency": "EUR",
      "processorName": "Redsys",
      "entityProcessorCode": "223170853",
      "authorisationCode": "980782",
      "transactionCode": "511860368261",
      "paymentOperationType": "PREAUTHORIZATION"
    },
    "payment": {
      "paymentId": "b64c83104e888e3c86d29326d8815ec31785b2b98b4d1d7ffdb90fc98cea8fef",
      "operationDate": "2017-11-28T09:13:57+00:00",
      "amount": 100,
      "currency": "EUR",
      "processorName": "Redsys",
      "entityProcessorCode": "223170853",
      "authorisationCode": "980782",
      "transactionCode": "511860368261",
      "paymentOperationType": "PAYMENT"
    },
    "paymentMethod": {
      "holderName": "John Doe",
      "creditCardType": "VISA",
      "firstNumbers": "454881",
      "lastNumbers": "0003"
    },
    "refunds": [
      {
        "paymentId": "1aa65894f36e84718b40032493259b39a033a060c4d1ab6b9c89add9f751ef8f",
        "operationDate": "2017-11-28T09:14:06+00:00",
        "amount": -1,
        "paymentOperationType": "REFUND"
      }
    ]
  }
}

With this method you can get all the Payment information. To perform this operation you have to send the request detailed below:

GET {mymoidServerUrl}/pay/order/{paymentOrderId}/receipt

Generate numeric code

Response by the API:

{
    "status": true,
    "code": 0,
    "data": {
        "shortCode": "Y4GKHG",
        "numericCode": "992147933347"
    }
}

Using this method you have the posibility to convert the Payment Order identifier (Short Code) into a numeric code, this could be useful for serveral uses as is the IVR integrations.

GET {mymoidServerUrl}/pay/ivr/code?shortCode={ShortCode}

Get payment order by numeric code

Response by the API:

{
    "status": true,
    "code": 0,
    "data": {
        "paymentOrderId": "40007f1d64dee5794573af9101856f11b1c63b91109123a259d54161b991c954",
        "shortCode": "Y4GKHG",
        "currencyCode": "EUR",
        "amount": 18400,
        "merchantId": "a63c1c35c746c7be262fa971a80466b1543c7eed39b17eab2256a1b4214522c3",
        "reference": "OXF-3479",
        "concept": "Oxford Shoes - Spanish Leather",
        "status": "AVAILABLE",
        "currentStatus": {},
        "expirationCard": "02/20",
        "holderName": "John Doe",
        "pan": "454881XXXXXX0003",
        "cardLink": "https://sandbox.mymoid.com/pay/cards/260f7a2306c5e5ec4e47d7ceb7ae39eb5adf77b9c03232bb04caed8d44b9c880",
        "creationDate": 1567065489000,
        "expirationDate": 1567151889000,
        "updateDate": 1567065489000,
        "merchant": {
            "firmName": "TECHNOactivity S.L",
            "imageId": "image"
        }
    }
}

You can get the Payment Order information by using the following method:

GET {mymoidServerUrl}/pay/ivr/order?numericCode={numericCode}

Payment form

Before using the form you must generate a Payment Order. This Payment Order must be in AVAILABLE status at the time of invoking the form. Within the form it is necessary to enter the data of the Payment method to execute the Payment. Workflow

Customization guide

The page where the amount and form are shown allows a basic customization of its elements, based on the presence of a main colour (required) and a second one (optional, for the background and heading).

Logo

Colours

Recomended Size

Currently the maximum height size of the form’s content is 702px (on desktop displays) or 450px approx. on mobile portrait displays.

The iframe content has been built responsively, so it will fit to the iframe’s width as the webpage resizes. That’s useful to set the width dynamically based on a percentage or setting it with a css media query.

But, on the other hand, you’ll need to set the height manually considering those limitations described above. It’s highly recommended that you set the iframe’s height with a media query, though

Basic Payment form

To pay a Payment Order we need to enter the card’s data that we are going to use in the Payment Order. This form is available in the following address:

{mymoidServerUrl}/tpv/?p={PaymentOrdershortCode}

with shortCode as the identifier returned when creating the Payment Order.

Once the client enters the card’s details, they will be redirected to the corresponding result screen.

Payment form appearance:

Payment form redirection parameters

Users can be redirected to specific URLs through a continue button once the Payment operation has been finalized and depending on its result. To do so, we have to configure some parameters in the form’s URL, as shown in the following examples.

Example of the url format with the final redirection parameters:

{mymoidServerUrl}/tpv/?p={shortCode}&urlok={URL_OK}&urlko={URL_KO}

Payment form appearance with acepted redirection Payment:

Payment form appearance with rejected redirection Payment:

Payment Method

Card vault

After making a payment the payment method is stored on our secure PCI environment.

Card attributes

Attribute Description
holderName The name that the customer use when he executed the transaction.
firstNumbers First 6 digits of the PAN.
lastNumbers Last 4 digits of the PAN.
cardBrand Brand of the card (Ej: VISA, MASTERCARD, etc).
expirationDate Expiration date of the card.
issuerBank Issuer bank for the card.
issuerCountry Country from the card.
createdAt The date when the card is stored on our system.
cardType The type of card (Ej: CREDIT, DEBIT, etc).
fingerPrint The “PAN + Expiration date” unique identifier.
cardLevel The level of the card (Ej: STANDARD, PREPAID BUSINESS, ELECTRON, etc).
transactions List of all the transaction that this card were used for your merchant.
references List of all the references that have this card added.

Get card

Response by the API:

{
    "holderName": "John Doe",
    "firstNumbers": "454881",
    "lastNumbers": "0003",
    "cardBrand": "VISA",
    "expirationDate": "12/25",
    "issuerBank": "SERVIRED SOCIEDAD ESPANOLA DE MEDIOS DE PAGO, S.A.",
    "issuerCountry": "SPAIN",
    "createdAt": "2019-11-06 09:39:37",
    "id": "d3352c252a23fa199c4be3981ff8e9795cef08eb0d9ca242ea7d3affd5aaa771",
    "cardType": "CREDIT",
    "fingerPrint": "fcac76ec0b687ee67ec4edc3cac278bf66b751cd54f8442f71cfbc0a13fd2342",
    "cardLevel": "CLASSIC",
    "transactions": [
        {
            "id": "18394",
            "transactionType": "PAYMENT",
            "shortCode": "32HRYN",
            "firstNumbers": "454881",
            "lastNumbers": "0003",
            "purchaseOrder": "573033177617",
            "createdAt": "2019-11-06 09:39:39",
            "amount": 1,
            "currency": "EUR"
        }
    ],
    "references": [
        {
            "createdAt": "2018-09-27 16:15:04",
            "referenceId": "51806965",
            "publicId": "e9a9fb5fd4227d4f243cb0e539a6b6f7bfb7a7905806793e92a36b41a94bfa3c"
        }
    ]
}

In order to get the card detailed information you must use te following request.

GET {mymoidServerUrl}/pay/cards/{paymentMethodId}

For more information about the card link, please refer to the Payment Order - Section

Payment form to reuse

One of the most interesting possibilities of this function is the capability to store a Payment Method without the need to make any charge on it.

To do so we will create a Payment Order for an amount of 0 EUR (or whatever other currency), then we will load its associated payment form and we will enter into it the payment method.

In this case, no charge is made on the Payment Method entered. It simply validates that its information is correct, as such the form does not show the amount of the Payment Order.

If the Payment Method is valid, the Payment Order will appear as paid and we can reuse it as many times as we want in order to reuse the Payment Method stored.

Payment form appearance

Reuse

The reuse is based on the same functionality as reissue. Its finality is to reuse a Payment Method already registered on our platform through a Payment Order already executed. The main difference with the previous method is that to execute a reuse its necessary to have two Payment Order identifiers, one from an order in AVAILABLE status and another from an order with PAID status.

Workflow

API call

Response by the API:

{
  "status": true,
  "code": 0,
  "data": {
    "paymentOrderId": "a08386cba9b4dd00640ffb0f188de26b45c87812cb43f2e00f30ca73d640968a",
    "shortCode": "HMQZ3P",
    "currencyCode": "EUR",
    "amount": 54821,
    "merchantId": "282682dd6b19c81ee7d6b3322505ebe20e03467c0a6dac129c2206e5202ba375",
    "reference": "MYMOID Reference test",
    "concept": "MYMOID Concept test",
    "status": "PAID",
    "currentStatus": {},
    "expirationCard": "01/18",
    "holderName": "John Doe",
    "pan": "454881XXXXXXXX0003",
    "cardLink": "https://sandbox.mymoid.com/pay/cards/260f7a2306c5e5ec4e47d7ceb7ae39eb5adf77b9c03232bb04caed8d44b9c880",
    "creationDate": 1491218865000,
    "payload": {
      "authorisationCode": "102435"
    }
  }
}

As we mentioned before, you can use the next request in order to reuse a Payment Method:

PUT {mymoidServerUrl}/pay/order/execute/{paymentOrderId}/reuse/{OriginalpaymentOrderId}

This request reuses the Payment Method used to pay the first Payment Order (field: OriginalpaymentOrderId) to pay the Payment Order in AVAILABLE status (field: paymentOrderId).

In order to reuse a Payment Method you have to make sure that you are using the credentials provided with this specific permissions.

You can check the permissions list in the Basic concepts - Application section.

API Errors

Mymoid Errors

In this section we will describe Payment errors returned by the API.

Error Code Meaning
Validator.mymoPay.3dsAuthenticationFailedError 3D Secure authentication failed
Validator.mymoPay.amountTooSmall Amount too small for this transaction
Validator.mymoPay.accountNumberFormatNotValid Account number is not of valid format
Validator.mymoPay.bicNotValid BIC code is not valid
Validator.mymoPay.ibanNotValid IBAN code is not valid
Validator.invalidCardNumber The card number is invalid
Validator.mymoPay.callToMerchantError Error calling the callback url in the application
Validator.mymoPay.cardBlockedByIssuerBankError Card is blocked by the issuer bank
Validator.mymoPay.cardNotVerified Card must be validated before being used
Validator.mymoPay.cardTemporallyBlockedbyIssuerBank Card is temporally blocked by the issuer bank
Validator.mymoPay.cardValidationError Card validation error
Validator.mymoPay.creditCardAlreadyVerifiedError This credit card has already been verified
Validator.mymoPay.creditCardDeleted Credit card deleted
Validator.mymoPay.creditCardVerificationError Error verifying credit card
Validator.mymoPay.creditCardVerificationMaxAttempts ReachedError Error verifying credit. The number of attempts to be verified has been reached
Validator.mymoPay.currencyNotAvailable Currency not available
Validator.mymoPay.currencyNotFound Currency not found
Validator.mymoPay.declinedCardError Declined card
Validator.mymopay.expirationDateFormatNotValid The expiration card number is on a wrong format
Validator.mymoPay.fraudSuspectCardError Fraud suspect card
Validator.mymoPay.gatewayConfigurationError Gateway configuration error
Validator.mymoPay.gatewayConnectionError Gateway connection error
Validator.mymoPay.gatewayError We cannot process payment because a problem on gateway
Validator.mymoPay.gatewayServiceError Gateway system error. Try in a few minutes
Validator.mymoPay.genericGatewayError Generic gateway error
Validator.mymoPay.incorrectOwnerRefund This merchant is not the owner of this payment order
Validator.mymoPay.insufficentBalance Insufficient balance
Validator.mymoPay.invalidCvvCodeError Cvv code is not correct
Validator.mymoPay.paymentMethodTypeNotValid Invalid payment method type
Validator.mymoPay.InvalidPaymentOrderStatus Invalid payment order status
Validator.mymoPay.redsysTokenFormatNotValid Invalid Redsys token
Validator.mymoPay.invalidUser Invalid user
Validator.mymoPay.invalidPaymentOrderParameters Invalid PaymentOrder parameters
Validator.mymoPay.merchantNotFound Merchant not found
Validator.mymoPay.operationNotAllowedCurrentGatewayError Operation not allowed for current gateway
Validator.mymoPay.operationNotAllowedForExternalMerchant Operation not allowed for external merchant. Trade t should contact the processing center to solve the problem.
Validator.mymoPay.paymentMethodAuthenticationError Error authenticating paymentMethod
Validator.mymoPay.paymentMethodExpired The Payment Method has expired
Validator.mymoPay.paymentMethodNotValid Operation not allowed for this payment method
Validator.mymoPay.paymentNotFound Payment not found
Validator.mymoPay.paymentOrderExpired Payment order has expired
Validator.mymoPay.paymentOrderNotFound Payment order not found
Validator.mymoPay.paymentOrderReissueError Error executing reissue operation
Validator.mymoPay.paymentOrderStatusUpdateFailed Payment order status could not be updated
Validator.mymoPay.paymentOrderUnavailable Payment order is not available
Validator.mymoPay.paymentOrderWithoutAmountCannotBeRefundedError Payment order with 0 amount cannot be refunded
Validator.mymoPay.paymentsNotFound Payments not found
Validator.mymoPay.payOrderCantBeExpired Payment order can’t be expired
Validator.mymoPay.payOrderStatusNotAllowed Operation not allowed for this order status
Validator.mymoPay.payTypeNotAllowed Pay type not allowed
Validator.mymoPay.promotionalCodeInvalidOrExpired The promotional code is not valid or has expired
Validator.mymoPay.refundAmountBiggerThanAvailable Refund amount is bigger than available amount
Validator.mymoPay.refundAmountTooHighError Refund amount is too high
Validator.mymoPay.refundNotAllowedError Refund not allowed
Validator.mymoPay.reusePaymentOrderError The payment order cannot be reused
Validator.mymoPay.securePaymentNotAllowedOnCurrentGatewayError Current gateway does not allow secure payment
Validator.mymoPay.temporaryBlockedOrFraudSuspectCardError Card temporary blocked by the issuer bank or fraud suspect
Validator.mymoPay.wrongMerchant Operation not allowed. Check application configuration

Processor Errors

KO response by the API from Redsys:

{
    "status": false,
    "code": 200,
    "data": [
        {
            "message": "Generic gateway error",
            "code": "Validator.mymoPay.genericGatewayError",
            "processor": {
                "name": "Redsys",
                "errorCode": "190"
            }
        }
    ]
}

KO response by the API from Worldpay:

{
    "status": false,
    "code": 200,
    "data": [
        {
            "message": "Generic gateway error",
            "code": "Validator.mymoPay.genericGatewayError",
            "processor": {
                "name": "Redsys",
                "errorCode": "190"
            }
        }
    ]
}

When you try to execute a payment a transaction between mymoid and the payment processor is made. If this transaction is denial by the processor we will provide you the infomation about the error code we receive from it, included in the “processor” section of the json sent to your system.

Below we provide you with the proceesor documentation where you can find a detailed explanation about each error code:

Woldpay error documentation. You can find all the errors descriptions availables under the label “ISO 8583 response codes”.

Redsys error documentation. On page 22 you can find a detailed explanation about redsys errors (Only spanish).

Bambora error documentation. In this document you can find a detailed information about Bambora errors (Under section ResponseCode1987).

Notifications

In this section we will describe notifications sent from MYMOID to merchants. We have two kinds of notifications: email and webhook.

The email notification sends information once a payment is made using MYMOID platform.

The webhook notification gives merchant information about a payment operation even if it has failed. As the email notification is enough descriptive by itself, we are going to describe more in detail the webhook notification below.

Webhook

Example of a successfull payment Webhook:

{
   "user":{
      "publicId": "anonymous",
      "paymentMethod":{
         "pan": "454881XXXXXX0004",
         "expirationDate": "12/20",
         "holderName": "John Doe"
      }
   },
   "paymentOrder":{
      "paymentOrderId": "982782aedde3956658a97886299743e9a8492b311abfef984fdd054c8ef31cf6",
      "concept": "Oxford Shoes - Spanish Leather",
      "currency": "EUR",
      "amount": 18400,
      "status": "PAID",
      "updatedAt": 1465315778000,
      "reference": "OXF-3479"
   },
   "application":{
      "id": "6f88f5d7f3eab7cf40b55b353a21af55ab199f5868cdcebf9b9c7f4639652c56",
      "name": "merchant_app"
   },
   "signature": "RQIqiHzECBoBTSWRwLmIO/+OHa6AhN2zh33WeObXZhahO8NFMNFol+TxzAPnlp7f3o5XERdY8+N+Xu2iUn6QLT3mwl2x0yHoNJrRSVt74w2vVJsS7Ns8gHctxSNRmGrCI9EmmcDQrl6pe/fkuqba4tBEApZZZCd0WAuZWvLwGYyI/e0satDi7uJcnz0QKpm3jkpvmPEvfKUthSP5isSmnwHQYFcCWtkmLS1+YzZrZKHlErSt3HhIEwbWxt7YO5tO8UbnECtSO0fvjx9I6kW3JGGhn3v1+NSrijEnhiFpKT/RDqlUiuu4vP7Z3bwE4eecMCd7lKCmohJktPbSwMXQSw==",
   "cardLink": "https://sandbox.mymoid.com/pay/cards/7e6f4a54626ba239ced425eebf34f7f89a67decedb5afc9ace0db8463d6b3bae"
}

Example of a failed payment Webhook:

{
   "user":{
      "publicId": "anonymous",
      "paymentMethod":{
         "pan": "454881XXXXXX0113",
         "expirationDate": "12/20",
         "holderName": "John Doe"
      }
   },
   "paymentOrder":{
      "paymentOrderId": "982782aedde3956658a97886299743e9a8492b311abfef984fdd054c8ef31cf6",
      "concept": "Oxford Shoes - Spanish Leather",
      "currency":"EUR",
      "amount": 18400,
      "status": "AVAILABLE",
      "updatedAt": 1465315494000,
      "reference": "OXF-3479"
   },
   "application":{
      "id": "6f88f5d7f3eab7cf40b55b353a21af55ab199f5868cdcebf9b9c7f4639652c56",
      "name": "merchant_app"
   },
   "error":{
      "message": "Invalid card number",
      "code": "Validator.invalidCardNumber"
   },
   "signature": "o+U3xVYTycAP/Rr3GxKSFm4xTRO+V/yEtCsmbLr36Trz65bZNBVFkRgYV9DJwLBrRR6CTvzyGigWNQT8BIUwIa7sDdHj8MyboaH7ZbO6ZgWZItjI1cLTT7t99H310RGNshYFvoeAkSd9q3IFp8ID5KS6vJumkXziSBcKl0BphXKuBitgrWyya7rg7sNshG6DjByypxmjyJ4EUsPG8MWj3tqHPMOnNRiuSMMX9f9DgaYyCjBQdetKjQY0E8afRjADgatUhS8PZLUzRdRAJqA/bHGnz5YApfp/GpwmqzdRg0SI8LutXlMRkJIafk8+Ni1KJwd7RWyW1SmHcPwXqhBJrA==",
   "processor":{
      "name":"Redsys",
      "errorCode":"SIS0093"
   }
}

After making a payment attempt, MYMOID creates a callback request to Merchant’s webhook URL. Callback messages contain payment related information and their sent event if the payment process fails. To ensure callback authenticity, MYMOID applies an electronic sign process to the most important fields of the message. Merchant can use the method described below for ensuring callback origin.

 Signing process

MYMOID uses a RSA public key scheme for signing webhook message content. We apply “SHA-256 signing algorithm with RSA encoding as defined in the ‘OSI Interoperability Workshop’ following PKCS #1 conventions”. Resulting signature is Base64 encoded and included in the webhook message under 'signature’ attribute.

Data structure to sign

The webhook fields used during the process are updatedAt, userPublicId, paymentOrderId, amount, currency, status and applicationId. You can see an example of the string used to sign below:

{updatedAt=1465315778000, userPublicId=anonymous, paymentOrderId=982782aedde3956658a97886299743e9a8492b311abfef984fdd054c8ef31cf6, amount=2, currency=EUR, status=PAID, applicationId=6f88f5d7f3eab7cf40b55b353a21af55ab199f5868cdcebf9b9c7f4639652c56}

You could ask for sandbox and production certificates in order to ensure webhooks authenticity.

Signature verification

Once you have the corresponding certificate, you have to use MYMOID’s public key included inside. You can extract the public key via console using the following command:

openssl x509 -pubkey -noout -in ‘CERTFICATE’ > ‘PUBLIC_KEY’

For content verification simply apply the following steps using the public key extracted above:

A) Convert the signature received on the webhook from Base64 to binary:

Echo –n “SIGNATURE_RAW” | base64 --decode > “SIGNATURE_FILE“

Example using aside successful webhook message:

echo -n "RQIqiHzECBoBTSWRwLmIO/+OHa6AhN2zh33WeObXZhahO8NFMNFol+TxzAPnlp7f3o5XERdY8+N+Xu2iUn6QLT3mwl2x0yHoNJrRSVt74w2vVJsS7Ns8gHctxSNRmGrCI9EmmcDQrl6pe/fkuqba4tBEApZZZCd0WAuZWvLwGYyI/e0satDi7uJcnz0QKpm3jkpvmPEvfKUthSP5isSmnwHQYFcCWtkmLS1+YzZrZKHlErSt3HhIEwbWxt7YO5tO8UbnECtSO0fvjx9I6kW3JGGhn3v1+NSrijEnhiFpKT/RDqlUiuu4vP7Z3bwE4eecMCd7lKCmohJktPbSwMXQSw==" | base64 --decode > signature-1.sign

B) Check the signature extracted previously obtained, using the certificate’s public key and the base string received in the webhook:

Echo –n “BASE_STRING” | openssl dgst –sha256 –verify “PUBLIC_KEY” --signature “SIGNATURE_FILE”

Example using aside successful webhook message:

echo –n "{updatedAt=1465315778000, userPublicId=anonymous, paymentOrderId=982782aedde3956658a97886299743e9a8492b311abfef984fdd054c8ef31cf6, amount=2, currency=EUR, status=PAID, applicationId=6f88f5d7f3eab7cf40b55b353a21af55ab199f5868cdcebf9b9c7f4639652c56} | openssl dgst -sha256 -verify pubkey.pem -signature signature-1.sign