Navbar

Get Started

Getting Started with Paga+Tarde Orders API

In this column you will find JSON objects and examples from what is described in the main column.

The Paga+Tarde APIs are HTTP-based RESTful APIs that uses Basic Auth for authorization. API request and response bodies are in JSON format.

The Paga+Tarde APIs enables full access to the services offered by Paga+Tarde for authorized merchants. If you do not have a merchant account yet, you can create one in the Merchant Backoffice.

Authentication

# Authentication Example using CURL in the command line
curl -v \
  -X GET \
  -u "tk_fd53cd467ba49022e4f8215d:21e57baa97459f6z" \
  -H "Content-Type:application/json" \
  https://api.pagamastarde.com/v2/orders/

Basic Authentication header

"Authorization: Basic base64(publicKey:privateKey)"

/*
 * There is a Client that will easy all the development.
 * Find the ordersApiClient in our public GitHub.com
 *
 * https://github.com/PagaMasTarde/ordersApiClient
 *
 * composer require pagamastarde/orders-api-client
 */

The Paga+Tarde REST API uses Basic Authentication to authorize the merchant calls. When registering at the Merchant Backoffice, Paga+Tarde generates a pair of API Keys that will be used for authentication within the API calls.

To get your own API Keys you can find them in the Merchant Backoffice under the Shop Details section.

The Public Key can be used within the HTML source, is secure to display this key. Some Javascript widgets that Paga+Tarde provides may require the use of this Public Key.

The Private Key or Secret key should never be displayed nor revealed. This Secret key along with the public key will grant access to the Paga+Tarde services.

To gain authorization in Paga+Tarde, include the header with user:password using PublicKey and PrivateKey in API requests within the Authorization header with the Basic authentication scheme.

See the sample request on the right column that uses a Basic Authentication token to list orders for a merchant.

API Requests

# Refund Example using CURL in the command line
curl -v \
  -X POST \
  -u "tk_fd53cd467ba49022e4f8215d:21e57baa97459f6z" \
  -H "Content-Type:application/json" \
  -d '{
        "promoted_amount": 0,
        "total_amount": 5
      }'
  https://api.pagamastarde.com/v2/orders/{orderId}/refunds
<?php

//Use the API Client to operate with the API
$orderApiClient = new PagaMasTarde\OrdersApiClient\Client(
    $publicKey,
    $privateKey
);

$order = $orderApiClient->getOrder($orderId);
echo $order->getStatus();

//The API Client generates the necessary call.

/*
 * The Order object is defined inside the library and is prepared for OOP.
 * The attributes work with GETTERS and SETTERS
 */

//To see the JSON result of a order Object:
echo json_encode(
  $order->export(),
  JSON_PRETTY_PRINT |
  JSON_UNESCAPED_SLASHES |
  JSON_UNESCAPED_UNICODE
);

//@See more info in the public GitHub.com repository of PagaMasTarde

Paga+Tarde API Services is a REST API, which means that every request has some typical components as any other REST API:

Component Description
HTTP Method GET Requests data from a source
POST Submits data to a resource to process
PUT Updates a resource
PATCH Partially updates a resource
DELETE Deletes a resource
URL to the API service https://api.pagamastarde.com/v2/
URI to the resource The resource to query, submit data to, update, or delete. Our valid resources are /orders and /settlements
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 or the Content-Type header.
A JSON request Body Required for most POST, PUT, and PATCH calls.

You can find as an example in the code column how to do a Refund with CURL or how to use the Client to interact with the API.

Query Parameters

When using the GET API calls, use the query string parameters to filter the results. For example, asking for the orders created yesterday.

For most REST GET calls, it is possible to 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.

HTTP request headers

The most commonly used HTTP request headers are:

Always use the Authorization header to gain access to the API, 401 Unauthorized will be the response if the authentication fails.

Header Description
Accept Required for operations with a response body.
Specifies the response format. The syntax is:
Accept: application/format
Where format is json.
Content-Type Required for operations with a request body.
Specifies the response format. The syntax is:
Content-Type: application/format
Where format isjson`.
Authorization To make REST API calls, include the Basic token in the Authorization header with the Basic authentication scheme:
Authorization: Basic Access-Token

API Responses

# Refund Example using CURL in the command line
curl -v \
  -X PUT \
  -u "tk_fd53cd467ba49022e4f8215d:21e57baa97459f6z" \
  -H "Content-Type:application/json" \
  -d '{
        "promoted_amount": 0,
        "total_amount": 5
      }'
  https://api.pagamastarde.com/v2/orders/{orderId}/refunds

# Response will be a JSON Object with the refund: 201 Created
{
    "total_amount": 5,
    "promoted_amount": 0,
    "refunded_merchant_cost": 0,
    "payment_processor_cost": 0,
    "id": "5b3f364bf1b7bf0005de5ede",
    "created_at": "2018-07-06T09:28:43.864"
}
<?php

//Use the API Client to operate with the API
$orderApiClient = new PagaMasTarde\OrdersApiClient\Client(
    $publicKey,
    $privateKey
);

$order = $orderApiClient->getOrder($orderId);
echo $order->getStatus();

/*
 * The Order object is defined inside the library and is prepared for OOP.
 * The attributes work with GETTERS and SETTERS
 *
 * The Response is parsed within the Client and is transformed into a Previously Defined Object with
 * useful methods.
 */

Paga+Tarde API calls return HTTP status codes depending on the result of the request. Some API calls also return bodies with JSON content that include information about the resource. It may also contain one or more contextual HATEOAS links to request more information about the object or execute the next steps in the application flow.

HTTP status codes

Each REST API request returns a success or error HTTP status code.

Success

In the responses, Paga+Tarde 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.
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

When facing an error you can find the error code in the HTTP response. Understanding the Error Codes will make easier to debug and find the right solution.

In the responses for failed requests, Paga+Tarde returns HTTP 4XX or 5XX status codes. Additional information regarding the error can be found in the body of the request in JSON format. Paga+Tarde returns in the responses these HTTP status codes for failed requests:

Status Code Typical error code and error message
400 Bad Request INVALID_REQUEST. The request is not well-formed, syntactically incorrect, or violates schema.
401 Unauthorized AUTHENTICATION_FAILURE. Authentication failed due to invalid authentication credentials.
403 Forbidden NOT_AUTHORIZED. Authorization failed due to insufficient permissions.
404 Not Found RESOURCE_NOT_FOUND. The specified resource does not exist.
405 Method Not Allowed METHOD_NOT_SUPPORTED. The server does not implement the requested HTTP method.
422 Unprocessable Entity UNPROCCESSABLE_ENTITY. The API cannot complete the requested action, or the request action is semantically incorrect or fails business validation.
500 Internal Server Error INTERNAL_SERVER_ERROR. An internal server error has occurred.
503 Service Unavailable SERVICE_UNAVAILABLE. Service Unavailable.

Validation errors

When a validation error occurs typically find a 400 or a 422 in the HTTP status code. Identify each field and verify with the documentation what are the validations needed. Also sometimes could be a business rule. For example, do not confirm a order with CREATED status. For validation errors, Paga+Tarde returns the HTTP 400 Bad Request status code.

To prevent validation errors, double check that the parameters are of the right type and conform to the type 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 the required formats.
Required Must be included in the request.
Currency Must be in cents, without decimals.
Date Dates must be in the format yyyy-MM-dd'T'hh:mm:ss

Authentication errors

All API calls must have the Authorization token included or will face a 401 Unauthorized.

  • For authentication errors, Paga+Tarde returns the HTTP 401 Unauthorized status code. See authentication and authorization.
  • Access token-related issues often cause authentication errors.
  • Ensure to send the right header with the right token.

HATEOAS

# Inside the Order object find the possible actions within the resource
{
  "action_urls": [{
    "href": "https://api.pagamastarde.com/v2/orders/36C38912MN9658832",
    "rel": "self",
    "method": "GET"
  }, {
    "href": "https://api.pagamastarde.com/v2/orders/36C38912MN9658832/refund",
    "rel": "refund",
    "method": "PUT"
  }]
}

Hypermedia as the Engine of Application State (HATEOAS) is a constraint of the REST application architecture that distinguishes it from other network application architectures.

On the right, there is a sample response that shows an array of HATEOAS links

Responses in Paga+Tarde API include HATEOAS links. This link present actions that can be triggered on the resource.

The elements in the link object are:

Element Required Description
href Required The target URL.
rel Required The link relationship type.
method Optional The HTTP method. The default is GET.

Orders Methods

Almost all interaction between Paga+Tarde and the merchant are through Orders. The following methods described below cover the functionality for a fully operational integration.

Find the objects descriptions in Orders Objects

Create Order

POST /orders
# Create Order Example using CURL in the command line
curl -v \
  -X POST \
  -u "tk_fd53cd467ba49022e4f8215d:21e57baa97459f6z" \
  -H "Content-Type:application/json" \
  -d '{
          "configuration": {
            ...
          },
          "metadata": {
            ...
          },
          "shopping_cart": {
            ...
          },
          "user": {
            ...
          }
      }'
  https://api.pagamastarde.com/v2/orders/

# The response is an Order Object:
{
    "shopping_cart": {
        "order_reference": "string",
        "total_amount": 20400,
        "promoted_amount": 0,
        "details": {
            "shipping_cost": 0,
            "products": [
                {
                    "description": "string",
                    "quantity": 2,
                    "amount": 10200
                }
            ]
        }
    },
    "user": {
        "full_name": "string",
        "email": "me@email.com",
        "dni": "string",
        "fix_phone": "string",
        "mobile_phone": "string",
        "address": {
            ...
        },
        "date_of_birth": "1987-01-31",
        "billing_address": {
            ...
        },
        "shipping_address": {
            ...
        },
        "order_history": [
            ...
        ]
    },
    "configuration": {
        ...
    },
    "metadata": {
        "additionalProp1": "string",
    },
    "id": "string",
    "api_version": "v2",
    "status": "CREATED",
    "created_at": "2018-07-06T10:20:15.075",
    "confirmed_at": null,
    "expires_at": "2018-07-06T12:20:15.075",
    "action_urls": {
        "form": "https://form.pagamastarde.com/orders/5b3f425f61b2e60005db9367"
    },
    "refunds": []
}
<?php

//Use the API Client to operate with the API
$orderApiClient = new PagaMasTarde\OrdersApiClient\Client(
    $publicKey,
    $privateKey
);

$order = new \PagaMasTarde\OrdersApiClient\Model\Order();
$order
    ->setConfiguration($configurationObject)
    ->setShoppingCart($shoppingCartObject)
    ->setUser($userObject)
    ->setMetadata($metadataObject)
;

//Notice, Create and fill with information the 4 objects

//To see the JSON result of a order Object:
echo json_encode(
  $order->export(),
  JSON_PRETTY_PRINT |
  JSON_UNESCAPED_SLASHES |
  JSON_UNESCAPED_UNICODE
);

//Finally create the order by using the client:
$orderCreated = $orderApiClient->createOrder($order);



/*
 * The Order object is defined inside the library and is prepared for OOP.
 * The attributes work with GETTERS and SETTERS
 *
 * The Response is parsed within the Client and is transformed into a Previously Defined Object with
 * useful methods.
 */

 /** @See https://github.com/PagaMasTarde/ordersApiClient **/


?>

@Exception Handling

use Try|Catch when using order Create method since it can cause HTTP exceptions.

When setting data into the order object there are Client Exceptions that may force to set the attributes in the
correct format.

Creating an order is the first step in Paga+Tarde. When a customer checks out in the merchant page then an order needs to be created in Paga+Tarde. On success, the API will return an Order Object that contains all the necessary information to process a payment, including a "form" URL to redirect the user to fill the Paga+Tarde form. After that, the user will be redirected again to the e-commerce website with the information regarding if the order was AUTHORIZED or REJECTED by Paga+Tarde.

Request

Argument Type Description
configuration Required Configuration The order configuration object.
metadata Required Metadata Order metadata object.
shopping_cart Required ShoppingCart Order ShoppingCart object.
user Required User Order User object.

Response

Argument Type Description
action_urls Required ActionUrls Possible actions to perform to the order.
api_version Required String Version of the API.
configuration Required Configuration The order configuration object.
confirmed_at Required Date Order confirmation date.
created_at Required Date Order creation date.
expires_at Required Date Order expiration date.
expires_at Required Date Order expiration date.
id Required String Order identification string.
metadata Required Metadata Order metadata object.
refunds Required Refund[] Order Refund array.
shopping_cart Required ShoppingCart Order ShoppingCart object.
status Required String Order current status.
user Required User Order User object.

Possible status codes:

Status Code Description
201 Created Order was successfully created.
401 Unauthorized Not enough privilege to perform the action
403 Forbidden Wrong token, please check the headers.
404 Not Found The orderId in the URL was not found.

Get Order

GET /orders/{orderId}
# Fetch an Order using CURL in the command line
curl -v \
  -X GET \
  -u "tk_fd53cd467ba49022e4f8215d:21e57baa97459f6z" \
  -H "Content-Type:application/json" \
  https://api.pagamastarde.com/v2/orders/{order_id}

# The response is the required Order Object:
{
    "shopping_cart": {
        "order_reference": "string",
        "total_amount": 20400,
        "promoted_amount": 0,
        "details": {
            "shipping_cost": 0,
            "products": [
                {
                    "description": "string",
                    "quantity": 2,
                    "amount": 10200
                }
            ]
        }
    },
    "user": {
        "full_name": "string",
        "email": "me@email.com",
        "dni": "string",
        "fix_phone": "string",
        "mobile_phone": "string",
        "address": {
            ...
        },
        "date_of_birth": "1987-01-31",
        "billing_address": {
            ...
        },
        "shipping_address": {
            ...
        },
        "order_history": [
            ...
        ]
    },
    "configuration": {
        ...
    },
    "metadata": {
        "additionalProp1": "string",
    },
    "id": "string",
    "api_version": "v2",
    "status": "CREATED",
    "created_at": "2018-07-06T10:20:15.075",
    "confirmed_at": null,
    "expires_at": "2018-07-06T12:20:15.075",
    "action_urls": {
        "form": "https://form.pagamastarde.com/orders/5b3f425f61b2e60005db9367"
    },
    "refunds": []
}
<?php

//Use the API Client to operate with the API
$orderApiClient = new PagaMasTarde\OrdersApiClient\Client(
    $publicKey,
    $privateKey
);

//By storing the Paga+Tarde order ID, fetch back the updated order:
$order = $orderApiClient->getOrder($orderId);

/*
 * The Order object is defined inside the library and is prepared for OOP.
 * The attributes work with GETTERS and SETTERS
 *
 * The Response is parsed within the Client and is transformed into a Previously Defined Object with
 * useful methods.
 */

 /** @See https://github.com/PagaMasTarde/ordersApiClient **/


?>

@Exception Handling

use Try|Catch when using get Order method since it can cause HTTP exceptions.



<?php

/** Tip: Navigate inside the fetched order properties:

/** $status array() **/
$status = $order->getStatus();

/** $amount int **/
$amount = $order->getShoppingCart()->getTotalAmount();

/** $createdAt \DateTime **/
$createdAt = $order->getCreateAt();

/** $refunds Refund[] **/
$refunds = $order->getRefunds();

Returns the required order object. This object has the necessary information to understand the status of a Payment as the next steps to be done and the amount.

Request

Direct call to fetch the order, no need for body nor query string parameters. This is a simple resource return API call.

Response

Order Object

Argument Type Description
action_urls Required ActionUrls Possible actions to perform to the order.
api_version Required String Version of the API.
configuration Required Configuration The order configuration object.
confirmed_at Required Date Order confirmation date.
created_at Required Date Order creation date.
expires_at Required Date Order expiration date.
expires_at Required Date Order expiration date.
id Required String Order identification string.
metadata Required Metadata Order metadata object.
refunds Required Refund[] Order Refund array.
shopping_cart Required ShoppingCart Order ShoppingCart object.
status Required String Order current status.
user Required User Order User object.

Possible status codes:

Status Code Description
200 OK Order was successfully retrieved.
401 Unauthorized Not enough privilege to perform the action
403 Forbidden Wrong token, please check the headers.
404 Not Found The orderId in the URL was not found.

List Orders

GET /orders
# List Orders using CURL in the command line
curl -v \
  -X GET \
  -u "tk_fd53cd467ba49022e4f8215d:21e57baa97459f6z" \
  -H "Content-Type:application/json" \
  https://api.pagamastarde.com/v2/orders?pageSize=2&page=1&status=CONFIRMED

# The response is the required list of Orders Object:
[
    {
        "id": "string",
        "status": "CONFIRMED",
        "id": "string",
        "api_version": "v2",
        "status": "CREATED",
        "created_at": "2018-07-06T10:20:15.075",
        "confirmed_at": null,
        "expires_at": "2018-07-06T12:20:15.075",
        "action_urls": {
            "form": "https://form.pagamastarde.com/orders/5b3f425f61b2e60005db9367"
        },
        "refunds": [],
        ...
        "configuration": {
            ...
        },
        "metadata": {
            ...
        },
        "shopping_cart": {
            ...
        },
        "user": {
            ...
        }
    },
    {
        "id": "string",
        "status": "CONFIRMED",
        "id": "string",
        "api_version": "v2",
        "status": "CREATED",
        "created_at": "2018-07-06T10:20:15.075",
        "confirmed_at": null,
        "expires_at": "2018-07-06T12:20:15.075",
        "action_urls": {
            "form": "https://form.pagamastarde.com/orders/5b3f425f61b2e60005db9367"
        },
        "refunds": [],
        ...
        "configuration": {
            ...
        },
        "metadata": {
            ...
        },
        "shopping_cart": {
            ...
        },
        "user": {
            ...
        }
    }
]
<?php

//Use the API Client to operate with the API
$orderApiClient = new PagaMasTarde\OrdersApiClient\Client(
    $publicKey,
    $privateKey
);

//Define the queryString parameters to filter:
$queryString = [
    'channel'       => 'online',
    'pageSize'      => 2,
    'page'          => 1,
    'status'        => Order::STATUS_CONFIRMED,
    'createdFrom'   => '2018-06-28T14:08:01',
    'createdTo'     => '2018-06-28T14:08:03',
];

$orders = $orderApiClient->listOrders($queryString);

/** @See https://github.com/PagaMasTarde/ordersApiClient **/

?>

@Exception Handling

use Try|Catch when using get Order method since it can cause HTTP exceptions.



<?php

/** Tip: Iterate inside the fetched list of Orders:

// Calculate the total amount of sales within the orders: List the orders from yesterday with status CONFIRMED and...

$amount = 0;

foreach ($orders as $order) {
    $amount += $order->getShoppingCart()->getTotalAmount();
}

// In cents, the total amount of sales from yesterday.
echo $amount;

Gets a list of orders that can be filtered and sorted. This service can be used to find orders in the system setting the query string with the right parameters.

Request

  • Request Can be filtered using the query string parameters shown below:
Query String Description
amountMax (required amountMin) Max amount of the order
amountMin (required amountMax) Min amount of the order
channel Defined channel of the order
createdFrom (required createdTo) Order creation date start
createdTo (required createdFrom) Order creation date end
haveRefunds true or false
orderReference Search by order reference
page Page number (required pageSize)
pageSize Page size (required page)
updatedFrom (required updatedTo) Order updated date start
updatedTo (required updatedFrom) Order updated date end
status Defined valid status

Response

The response is an array of Order objects

Possible status codes:

Status Code Description
200 OK List was successfully retrieved.
401 Unauthorized Not enough privilege to perform the action
403 Forbidden Wrong token, please check the headers.
404 Not Found The orderId in the URL was not found.

Confirm Order

PUT /orders/{orderId}/confirm
# Confirm Order using CURL in the command line
curl -v \
  -X PUT \
  -u "tk_fd53cd467ba49022e4f8215d:21e57baa97459f6z" \
  -H "Content-Type:application/json" \
  https://api.pagamastarde.com/v2/orders/{orderId}/confirm

# The response is the order object:
[
    {
        "id": "string",
        "status": "CONFIRMED",
        "id": "string",
        "api_version": "v2",
        "status": "CREATED",
        "created_at": "2018-07-06T10:20:15.075",
        "confirmed_at": null,
        "expires_at": "2018-07-06T12:20:15.075",
        "action_urls": {
            "form": "https://form.pagamastarde.com/orders/5b3f425f61b2e60005db9367"
        },
        "refunds": [],
        ...
        "configuration": {
            ...
        },
        "metadata": {
            ...
        },
        "shopping_cart": {
            ...
        },
        "user": {
            ...
        }
    },
    {
        "id": "string",
        "status": "CONFIRMED",
        "id": "string",
        "api_version": "v2",
        "status": "CREATED",
        "created_at": "2018-07-06T10:20:15.075",
        "confirmed_at": null,
        "expires_at": "2018-07-06T12:20:15.075",
        "action_urls": {
            "form": "https://form.pagamastarde.com/orders/5b3f425f61b2e60005db9367"
        },
        "refunds": [],
        ...
        "configuration": {
            ...
        },
        "metadata": {
            ...
        },
        "shopping_cart": {
            ...
        },
        "user": {
            ...
        }
    }
]
<?php

//Use the API Client to operate with the API
$orderApiClient = new PagaMasTarde\OrdersApiClient\Client(
    $publicKey,
    $privateKey
);

$order = $orderApiClient->confirmOrder($orderId);

/** @See https://github.com/PagaMasTarde/ordersApiClient **/

?>

@Exception Handling

use Try|Catch when using get Order method since it can cause HTTP exceptions.

<?php

/** Tip: List the AUTHORIZED orders and confirm them to prevent loosing any transaction:

$authorizedOrders = $orderApiClient->listOrders([
    'status' => Order::STATUS_AUTHORIZED,
]);

foreach ($orders as $order) {
    // validate the payment in the merchant system and then inform Paga+Tarde API that
    // the order is processed and valid in the merchant
    $orderConfirmed = $orderApiClient->confirmOrder($order->getId());
}

?>

Remember that if an AUTHORIZED order is not confirmed, the payment will
be released and the loan will not be created. It is mandatory to
confirm all AUTHORIZED orders.

When the order is AUTHORIZED then the merchant needs to confirm it. Confirmed orders are processed and the loan is created. Once a loan is confirmed it is able to have refunds. To cancel a confirmed order it should be done through a total refund.

Several callbacks URLs can be added to the order for notification of orders authorized and rejected. Also, it is possible to list all the orders that are pending confirmation using the GET Orders.

Request

  • Request has no body, only query string parameters.

Response

Argument Type Description
action_urls Required ActionUrls Possible actions to perform to the order.
api_version Required String Version of the API.
configuration Required Configuration The order configuration object.
confirmed_at Required Date Order confirmation date.
created_at Required Date Order creation date.
expires_at Required Date Order expiration date.
expires_at Required Date Order expiration date.
id Required String Order identification string.
metadata Required Metadata Order metadata object.
refunds Required Refund[] Order Refund array.
shopping_cart Required ShoppingCart Order ShoppingCart object.
status Required String Order current status.
user Required User Order User object.

Possible status codes:

Status Code Description
200 OK Order was successfully confirmed.
401 Unauthorized Not enough privileges to perform an action
403 Forbidden Wrong token, please check the headers.
404 Not Found The orderId in the URL was not found.

Refund Order

POST /orders/{orderId}/refund
# Refund partially an order using CURL in the command line
curl -v \
  -X POST \
  -u "tk_fd53cd467ba49022e4f8215d:21e57baa97459f6z" \
  -H "Content-Type:application/json" \
  -d '{
        "promoted_amount": 0,
        "total_amount": 5
      }'
  https://api.pagamastarde.com/v2/orders/{orderId}/refunds

# The response is the refund object:
{
    "total_amount": 5,
    "promoted_amount": 0,
    "refunded_merchant_cost": 0,
    "payment_processor_cost": 0,
    "id": "5b433007f1b7bf0005de5ee4",
    "created_at": "2018-07-09T09:51:03"
}
<?php

//Use the API Client to operate with the API
$orderApiClient = new PagaMasTarde\OrdersApiClient\Client(
    $publicKey,
    $privateKey
);

//Create a Refund object and set the amounts:
$refund = new PagaMasTarde\OrdersApiClient\Model\Order\Refund();
$refund
    ->setPromotedAmount(0)
    ->setTotalAmount(10)
;

//Then use the API client to generate a the refund:
$refundCreated = $apiClient->refundOrder($orderId, $refund);

/** @See https://github.com/PagaMasTarde/ordersApiClient **/

?>

@Exception Handling

use Try|Catch when using get Order method since it can cause HTTP exceptions.

To refund an order you can use this method to modify the total_amount of the original order. Refunds can only be requested over a confirmed order. The refund of an order affects the amount to pay in each instalment.

An order can have several refunds, as long as the sum of all refunds does not reach the order total_amount. Once the entire total_amount is refunded the order status will change to CANCELLED.

The list of applied refunds is returned with the order, use the Get Order method to retrieve them.

Request

Argument Type Description
total_amount Required Int the amount in cents to refunded from the total_amount of the order
promoted_amount Optional Int the amount in cents to be refundeded from total_amount considered as promotional.

Response

Argument Type Description
id Required String The id of the Refund object created. This is not the id of the order.
total_amount Required Int the amount in cents refunded from the original total_amount
promoted_amount Required Int the amount in cents refunded from total_amount considered as promotional.
payment_processor_cost Required Int the amount in cents that generated by the payment processor cost.
refunded_merchant_cost Required Int the amount in cents that will be deducted from the settlement as a cost.
created_at Required Date the moment when the request was processed.

Possible status codes:

Status Code Description
201 Created Refund was successfully created.
401 Unauthorized Not enough privileges to perform the action
403 Forbidden Wrong token, please check the headers.
404 Not Found The orderId in the URL was not found.

Orders Reference

Orders Objects

Configuration

{
    "channel": {
        "type": "ONLINE",
        "assisted_sale": false
    },
    "urls": {
        "ok": "https://my-store.com/order-approved",
        "ko": "https://my-store.com/order-rejected",
        "cancel": "https://my-store.com/order-cancelled",
        "authorized_notification_callback": "https://my-store.com/orders/notify",
        "rejected_notification_callback": "https://my-store.com/orders/notify"
    }
}

The configuration object contains the information regarding the source of the Order and configures the actions to take upon user experience.

  • channel: REQUIRED OBJECT
    • type: REQUIRED ENUM
      ONLINE, INSTORE
      Configuration of the sale channel, use this to identify the origin of the order.
    • assisted_sale: REQUIRED Boolean
      true, false
      Indicates whether there is a real human clerk assisting the sale. Should be false for INSTORE type orders when the clerk does not follow the Paga+Tarde form filling and an SMS or Email is used instead, ONLINE orders should always be false
  • urls: REQUIRED OBJECT
    • cancel: REQUIRED String
      Redirect location for cancelled payment, event triggered by the user.
    • ko: REQUIRED String
      Redirect location for rejected payment, upon not accepted payment the user is sent back to the merchant. The best practice is to show again the checkout.
    • authorized_notification_callback: OPTIONAL String
      After order status change to AUTHORIZED system triggers a Authorized Notification Callback for information purpose to defined URL.
    • rejected_notification_callback: OPTIONAL String
      After order status change to REJECTED system triggers a Rejected Notification Callback for information purpose to defined URL.
    • ok: REQUIRED String
      Redirect location for authorized payment, upon accepted payment the user is sent back to the merchant. Merchant has to confirm the order to proceed finally to create a loan.

Address

{
    "full_name": "string",
    "address": "string",
    "city": "string",
    "zip_code": "string",
    "country_code": "ES",
    "dni": string,
    "fix_phone": 958865165,
    "mobile_phone": 600123123
}

The object address is the sum of properties that represents a location and identifies a person.

  • full_name: REQUIRED String
    Full name of the user
  • address: REQUIRED String
    Street, number, and others
  • city: REQUIRED String
    The city of the address
  • country_code: REQUIRED String
    The country code of the address. (ES,FR,PT)
  • zip_code: OPTIONAL String
    The zip code of the city, for example: 28008
  • dni: OPTIONAL String
    Id card number of the user
  • fix_phone: OPTIONAL String
    Fixed phone of the address
  • mobile_phone: OPTIONAL String
    Mobile phone of the user

Product

{
    "amount": 49999,
    "description": "TV47LG4k with SoundBar",
    "quantity": 1
}

Representation of an item or service that the user is purchasing

  • amount: REQUIRED Int
    In cents, the total amount of the product
  • description: REQUIRED String
    Product name, or description.
  • quantity: REQUIRED Int
    Number of items purchased

Shopping Cart

{
    "products": [
        {
          "amount": 10200,
          "description": "Ipod Touch 3G",
          "quantity": 1
        },
        {
          "amount": 999,
          "description": "Headset SONY UltraBass",
          "quantity": 2
        }
    ],
    "shipping_cost": 499
    "order_reference": "myshop-123",
    "promoted_amount": 0,
    "total_amount": 11698
}

The shopping cart object is mandatory and defines the items and the price of each of them that will be purchased

  • products: REQUIRED Product[]
    Array of product objects. At least one of them is mandatory.
  • shipping_cost: OPTIONAL Int
    The shipping cost in cents of the order.
  • order_reference: OPTIONAL String
    The Order ID in the merchant system. If present will help later to find and identify the order.
  • promoted_amount: OPTIONAL Int
    The part of total_amount for what the customer will not pay interests. The merchant will cover those costs. Should be equal to total_amount or smaller, in cents.
  • total_amount: REQUIRED Int
    The total amount of the order in cents. This is what the user will be charged for.

Refund

{
    "total_amount": 5,
    "promoted_amount": 0,
    "refunded_merchant_cost": 0,
    "payment_processor_cost": 0,
    "id": "5b43616361b2e60005db9380",
    "created_at": "2018-07-09T13:21:39"
}

If the order has at least one refund, then the object will have a Refunds collection with the complete list of refunds.

  • id: REQUIRED String
    Refund ID in Paga+Tarde
  • promoted_amount: REQUIRED Int
    The amount in cents of the part of the refund that was promoted.
  • created_at: REQUIRED Date
    The date time when the refund was created.
  • total_amount: REQUIRED Int
    The total amount of the refund, in cents.
  • refunded_merchant_cost: REQUIRED Int
    The merchant cost for the refund, in cents.
  • payment_processor_cost: REQUIRED Int
    The cost for the payment processor, in cents.

User

{
    "full_name": "string",
    "email": "me@email.com",
    "dni": "string",
    "fix_phone": "string",
    "mobile_phone": "string",
    "date_of_birth": "1987-01-31",
    "address": {
        //Address object
    },
    "billing_address": {
        //Address object
    },
    "shipping_address": {
        //Address object
    },
    "order_history": [
        {
            "date": "2010-01-31",
            "amount": 200
        }
    ]
}

The user object describes the customer properties. Mandatory to create an order.

  • address: OPTIONAL Adress Object
    The current address of the user.
  • billing_address: OPTIONAL Adress Object
    The billing address of the order.
  • date_of_birth: OPTIONAL Date
    The date of birth for the user 'YYYY-MM-DD'
  • dni: OPTIONAL String
    The dni of the user. Used to identify recurring users.
  • email: REQUIRED String
    The email of the user.
  • fix_phone: OPTIONAL String
    The fixed phone number for the user.
  • full_name: REQUIRED String
    The full name of the customer.
  • mobile_phone: OPTIONAL String
    The mobile phone number of the user.
  • order_history: OPTIONAL Array
    An array with the previous orders of customer.
  • shipping_address: OPTIONAL Adress Object
    The shipping address of the order.

Action URLs

{
    "confirm": "string",
    "form": "string",
    "instore_email": "string",
    "instore_sms": "string",
    "refund": "string",
}

The Action URLs object contains the URLs of the possible actions to be performed on the object. Not all of them will be present all the time. Depending on the status the urls will be shown or not. For example, an order not confirmed cannot be refunded.

  • confirm: OPTIONAL String
    Url for order confirmation.
  • form: OPTIONAL String
    Url for redirect the user to Paga+Tarde payment form.
  • instore_email: OPTIONAL String
    Url to send a mail to a user for an in-store order.
  • instore_sms: OPTIONAL String
    Url to send an SMS to a user for an in-store order.
  • refund: OPTIONAL String
    Url where to perform a refund.

Metadata

{
    "merchant_user_id": "23",
    "merchant_shop_id": "5",
    "additionalProp3": "string",
}

The metadata object allows attaching information to the order. Anything that is interesting to keep attached for the order can be sent.

For example the customer id in the merchant side, or special ticket information. There is no validation in these fields.

The information should be stored with "key" => "value".


Order Status

The order will pass through several statuses during its lifespan. The status of an order can be obtained doing calling the Get Order service.

Status Machine

Created

CREATED Initial status of an order when it is created and not yet evaluated by Paga+Tarde.

Authorized

AUTHORIZED means that the order has been admitted and the user has paid the first instalment. In this status, only the confirmation of the merchant is remaining to finalize payment.

Rejected

REJECTED order has not been authorized by Paga+Tarde and therefore the user will be redirected to KO url.

Invalidated

INVALIDATED order has expired before reaching the authorized status, usually when the user closes the browser before finishing the process and abandons the cart. Another order has to be created in order to proceed with the payment.

Error

ERROR non-recoverable. Please contact merchant care.

Confirmed

CONFIRMED order is finalized. The order is processed and completed.

Unconfirmed

UNCONFIRMED is an order that becomes AUTHORIZED and the merchant does not confirm the order. In this case, the order is not processed and the payment is released.


Notifications

Notification callbacks will be sent when an order status change to AUTHORIZED or to REJECTED.

If you set the notification callbacks urls to a valid url you can manage the orders flow.

You will receive a GET request to the specified rejected_notification_callback or authorized_notification_callback.

This request will come with the parameter pmt_order_id as part of the query string of the url provided.

Examples:

GET: https://my-store.com/orders/notify/authorized?pmt_order_id=5be04969b194b2000544d560

GET: https://my-store.com/orders/notify/rejected?pmt_order_id=5be04969b194b2000544d560


API Flow

Orders diagram


Settlements Methods

The Paga + Tarde settlements API provides you an easy way to consult the settlements asociated to your account with us.

You can list all your settlements or view the detail of each one.

List Settlements

GET /settlements
# List Settlements using CURL in the command line
curl -v \
  -X GET \
  -u "tk_fd53cd467ba49022e4f8215d:21e57baa97459f6z" \
  -H "Content-Type:application/json" \
  https://api.pagamastarde.com/v2/settlements

# The response is the required list of Orders Object:
[
    {
        "id": "5bac39d038baeb0005cdb003",
        "created": "2018-09-27T02:00:48.984+0000",
        "sales_amount": 131800,
        "refunds_amount": 0,
        "amount_to_settle": 131141,
        "interest": 0,
        "commission": -659,
        "operations": [
            {
                "type": "SALE",
                "id": "5ba28135025c650001bd7469",
                "commission": -659,
                "created": "2018-09-19T17:13:03.183+0000",
                "amount": 131800,
                "amount_to_settle": 131141,
                "interest": 0,
                "order_id": "5ba28135025c650001bd7469",
                "order_reference": "97",
                "number_of_installments": 4
            }
        ]
    }
    ...
]

Gets a list of settlements asociated to a merchant.

Request

Direct call to fetch al list settlement, no need for body nor query string parameters.

  • Request Can be filtered using the query string parameters shown below:
Query String Description
createdFrom (required createdTo) Settlement creation date start
createdTo (required createdFrom) Settlement creation date end

Response

The response is an array of Settlements objects

Possible status codes:

Status Code Description
200 OK Settlement was successfully retrieved.
401 Unauthorized Not enough privilege to perform the action
403 Forbidden Wrong token, please check the headers.
404 Not Found No settlements were found for the merchant.

Get Settlement

GET /settlements/{settlementId}
# Fetch a Settlements using CURL in the command line
curl -v \
  -X GET \
  -u "tk_fd53cd467ba49022e4f8215d:21e57baa97459f6z" \
  -H "Content-Type:application/json" \
  https://api.pagamastarde.com/v2/settlements/{settlement_id}

# The response is the required Order Object:
{
    "id": "5bac39d038baeb0005cdb003",
    "created": "2018-09-27T02:00:48.984+0000",
    "sales_amount": 131800,
    "refunds_amount": 0,
    "amount_to_settle": 131141,
    "interest": 0,
    "commission": -659,
    "operations": [
        ...
    ]
}

Returns the required order object. This object has the necessary information to manage a settlement and its operations.

Request

Direct call to fetch the settlement, no need for body nor query string parameters. This is a simple resource return API call.

Response

Api responses are in JSON format with this structure

Settlement object

Argument Type Description
id Required String Settlement Identificator.
created Required Date Settlement creation date.
sales_amount Required Integer Full amount of the sale.
refunds_amount Required Integer Full refund amount of the sale.
amount_to_settle Required Integer Full amount to settle.
interest Required Integer Rate of interest.
commission Required Integer Commission of the settlement.
operations Required Operation[] Array of operations objects.

Operations object structure

Possible status codes:

Status Code Description
200 OK Settlement was successfully retrieved.
401 Unauthorized Not enough privilege to perform the action
403 Forbidden Wrong token, please check the headers.
404 Not Found The Settlement Identificator provided in the URL was not found.

Settlements Reference

Settlements Objects

Operation

{
    "type": "SALE",
    "id": "5ba28135025c650001bd7469",
    "commission": -659,
    "created": "2018-09-19T17:13:03.183+0000",
    "amount": 131800,
    "amount_to_settle": 131141,
    "interest": 0,
    "order_id": "5ba28135025c650001bd7469",
    "order_reference": "97",
    "number_of_installments": 4
}

An operation is a part of a shettlement that defines all or a part of it movements.

  • type: REQUIRED ENUM
    SALE, REFUND
    Kind of operation:
  • id: REQUIRED Date
    Settlement creation date.
  • commission: REQUIRED Integer
    Commission of the operation.
  • created: REQUIRED Date
    Operation creation date.
  • amount: REQUIRED Integer
    Operation amount
  • amount_to_settle: REQUIRED Integer
    Current operation amount to settle.
  • interest: REQUIRED Integer
    Rate of interest.
  • order_id: REQUIRED String
    Paga + Tarde order referenced indentificator
  • order_reference: REQUIRED Date
    Merchant order identificator
  • number_of_installments: REQUIRED Integer
    Number of installments of the operation