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

mymoidFormUrl: https://sandbox-tpv.mymoid.com

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

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

mymoidFormUrl: https://tpv.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

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

Payment Order statuses

Payment Order attributes

Payment attributtes

Refund attributtes

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"
}

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.

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"
    },
    "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

• PNG-24 image (transparent)
• Max. height: 40px
• Max. width: 150px
• Resolution @1x/@2x

Colours

• Button colour (Primary - Required):

  Hex colour or RGB colour

• Background colour (Secondary - Optional):

  Hex colour or RGB colour

• Header colour (Optional):

  Hex colour or RGB colour

• Concept / Reference (Required):

  Visibility: visible / hidden

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:

{mymoidFormUrl}/?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:

{mymoidFormUrl}/?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

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.

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

Credorax error documentation. There you can find more information about Credorax errors description under document "[Credorax] Source Payment API" - Section Appendix B: Operation Result Codes.

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

• Getting public key

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’

• Content verification

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