Centro de Soporte

We will define how MYMOID's payment API works throughout this section. This documentation is directed to the development departments of businesses that want to integrate, as such it has a technical nature. This guides assume that your company has been previously registered and that it has the necessary credentials to be able to interact with the payment API. We will discuss the following contents:

1. Introduction
2. API calls
3. MYMOID environments
4. PaymentOrder
5. PaymentOrder statuses
   
6. Creating a PaymentOrder
7. Cancelling a PaymentOrder
8. Checking the status of a PaymentOrder
9. Paying a PaymentOrder
10. Making a refung on a PaymentOrder

1.- Introduction

MYMOID's API consists of an API REST with a series of services secured by unique credentials assigned to each business. The entire API is based on the concept of a payment order (hereafter called PaymentOrder). This PaymentOrder reflects a payment and the interaction between a business and a client. As such, this document will make constant references to this term, which we will define with greater detail in the corresponding section.

2.- API calls

All API calls which are not public must have a specific HTTP header in all the 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 which the header must carry is composed of the following manner:

'Basic ' + Base64( 'application ID' + ':' + 'Secret application key')

In the first place, the application ID must be linked, followed by the symbol ':' and the secret application key. 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 is a blank space). We are going to see how to form it with the following example data:

Application ID: 5f93015589fcea018f0c2d97bd0a3508186a8b7d360591b0547d0743de2fe284
Secret application key: 97158fbb7852bfa0661033650a721ff7b97a3c1a0d41aafaa680b6f68c786196
Authorization header:

Basic NWY5MzAxNTU4OWZjZWEwMThmMGMyZDk3YmQwYTM1MDgxODZhOGI3ZDM2MDU5MWIwNTQ3ZDA3NDNkZTJmZTI4NDo5NzE1OGZiYjc4NTJiZmEwNjYxMDMzNjUwYTcyMWZmN2I5N2EzYzFhMGQ0MWFhZmFhNjgwYjZmNjhjNzg2MTk2

The authorization header which must be included in the request to the API would be the following:

 

Authorization                Basic NWY5MzAxNTU4OWZjZWEwMThmMGMyZDk3YmQwYTM1MDgxODZhOGI3ZDM2MDU5MWIwNTQ3ZDA3NDNkZTJmZTI4NDo5NzE1OGZiYjc4NTJiZmEwNjYxMDMzNjUwYTcyMWZmN2I5N2EzYzFhMGQ0MWFhZmFhNjgwYjZmNjhjNzg2MTk2

 

3.- MYMOID environments

MYMOID's API has two environments..

The first will be dedicated to integration trials for new companies, which we will call the SandBox. In this environment, there will be no real movement of money and all the tests will be performed with a testing card. In this environment, we cannot enter a real payment card 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:

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

The second environment will be the real environment named production. All the operations in this environment will be valid and it will only accept real cards. The configuration data of this environment are:

mymoidServerUrl: https://api.mymoid.com

All the requests function the same in both environments, the only aspect that changes is the url and a company's credentials. Once a company has been integrated in SandBox, if all its requests function correctly, it would only have to replace the url of one environment for another as well as its credentials.

4.- PaymentOrder

As we have already mentioned in the previous section, the entire MYMOID payment API will be based on the PaymentOrder concept. A PaymentOrder shall have the following attributes:

currency: the type of currency associated to the payment order.

reference: reference of the payment order.

concept: concept of the payment order.

amount:  amount of the payment order. This is an integer quantity (does not accept decimals) and represents the value in cents. To order a payment order of 1 Euro the value would be 100.

payType: type of payment order. The value that we must enter is PAY.

status: status of the payment order (detailed in the following section).

paymentOrderId: identifier of the payment order.

shortCode: short identifier of the payment order.

5.- PaymentOrder statuses

PaymentOrder can have the following statuses:

AVAILABLE: Available. The initial status of a payment order after it has been created.

EXPIRED: 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.

CANCELLED: Cancelled. A payment order with AVAILABLE status may be cancelled.

PAID: Paid. A payment order can only arrive to this status from AVAILABLE.

PARTIALLY_REFUNDED: Partially refunded. A payment order will be in this status if we make a refund for an amount less than the total after having been paid.

REFUNDED: 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.

6.- Creating a PaymentOrder

After defining PaymentOrder and the different statuses for PaymentOrders, 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

 

 

If we want to create a normal payment order, the body of the request would be the following:

 

{
  "currency": "EUR",
  "reference": "referencia del PaymentOrder",
  "amount": 2,
  "payType": "PAY",
  "concept": "concepto del PaymentOrder"
}

The response returned by the API will have the following format:

 

{
  "status": true,
  "code": 0,
  "data": {
    "paymentOrderId": "2e0d250097047b7abf1528fd271dd08cb8bc7b3fb7f51e37b3c8fc5c1eb19ec8",
    "shortCode": "JZ3PLK",
    "currencyCode": "EUR",
    "amount": 2,
    "merchantId": "282682dd6b19c81ee7d6b3322505ebe20e03467c0a6dac129c2206e5202ba375",
    "reference": "referencia del PaymentOrder",
    "concept": "concepto del PaymentOrder",
    "status": "AVAILABLE",
    "currentStatus": {},
    "creationDate": 1454490217151
  }
}

 

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 field. This unique identifier also represents a payment order and we will need it when loading the payment form that we will discuss later.

7.- Cancelling a PaymentOrder

After creating a payment order, we will 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}

 

And the response received from the API:

 

{
  "status": true,
  "code": 0,
  "data": {
    "paymentOrderId": "04a2cda611b5e2f7b18a6ad5b713b602e84502df690ac3dd2bdae14b46d6fdd8",
    "shortCode": "YY2HHG",
    "currencyCode": "EUR",
    "amount": 2,
    "merchantId": "282682dd6b19c81ee7d6b3322505ebe20e03467c0a6dac129c2206e5202ba375",
    "reference": "referencia del PaymentOrder",
    "concept": "concepto del PaymentOrder",
    "status": "CANCELLED",
    "currentStatus": {},
    "creationDate": 1454514264000
  }
}

8.- Checking the status of a PaymentOrder

Once a payment order has been created, we can consult its status at any time. This request will provide us the up-to-date information associated with the received payment order as a parameter. To do so, we will 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. The response from the API to this request will be the following:

 

{
  "status": true,
  "code": 0,
  "data": {
    "paymentOrderId": "04a2cda611b5e2f7b18a6ad5b713b602e84502df690ac3dd2bdae14b46d6fdd8",
    "shortCode": "YY2HHG",
    "currencyCode": "EUR",
    "amount": 2,
    "merchantId": "282682dd6b19c81ee7d6b3322505ebe20e03467c0a6dac129c2206e5202ba375",
    "reference": "referencia del PaymentOrder",
    "concept": "concepto del PaymentOrder",
    "status": "CANCELLED",
    "currentStatus": {},
    "creationDate": 1454514264000
  }
}

If the payment order is in the PAID status, we can see two fields that will be useful for us: pan and expirationCard. The pan reflects the last four digits of the card used to make the payment, while expirationCard shows its expiration date.

9.- Paying a PaymentOrder

To pay a payment order we will have to enter the data of the card that we are going to use in the payment order. This form is available in the following address: {mymoidServerUrl}/tpv/?p={shortCode}, with shortCode as the identifier returned when creating the payment order. In the case of the payment order that we have generated previously, the url would be: {mymoidServerUrl}/tpv/?p=JZ3PLK . The payment form will have the following appearance: