Pago

Se identifica como pago, a una transacción realizada por el usuario dentro de una sesión de pago.

POST/api/reverse

Reversar pago

Permite revertir un pago aprobado con el código de referencia interna internalReference.

Solicitud

  • Name
    auth
    Type
    Authentication
    is Required
    REQUIRED
    Description

    La autenticación del sitio. Ver más en Autenticación

    • Name
      login
      Type
      string
      is optional
      Description

      Identificador del sitio.

    • Name
      tranKey
      Type
      string
      is optional
      Description

      Credencial tranKey generado.
      Ver más en Autenticación

    • Name
      nonce
      Type
      string
      is optional
      Description

      Valor aleatorio para cada solicitud codificado en Base64.

    • Name
      seed
      Type
      string
      is optional
      Description

      Fecha actual, la cual se genera en formato ISO 8601.

  • Name
    internalReference
    Type
    integer
    is Required
    REQUIRED
    Description

    Referencia interna única de la transacción

    EJ: 543423

  • Name
    amount
    Type
    Amount
    is optional
    Description

    Información del monto a cobrar. Esta propiedad se envía cuando se desea realizar un reverso con un valor menor al monto total de la transacción.

    • Name
      currency
      Type
      string
      is optional
      Description

      Código alfabético de la moneda a usar (ISO 4217 alpha code)
      EJ: USD

    • Name
      total
      Type
      number
      is optional
      Description

      Valor total en la moneda base indicada
      EJ: 1000 equivalen a Mil dolares

    • Name
      taxes
      Type
      array[Taxes]
      is optional
      Description

      Estructura para definir impuestos en el proceso de pago.

      • Name
        kind
        Type
        string
        is optional
        Description

        Identificador del tipo de impuesto

        Uno de: valueAddedTax exciseDuty ice airportTax stateTax reducedStateTax municipalTax.

      • Name
        amount
        Type
        number
        is optional
        Description

        Monto total del impuesto
        EJ: 200

      • Name
        base
        Type
        number
        is optional
        Description

        Monto base sobre el cual se calcula el impuesto
        EJ: 1000

    • Name
      details
      Type
      array[Details]
      is optional
      Description

      Estructura para definir detalles adicionales del monto en el proceso de pago.

      • Name
        kind
        Type
        string
        is optional
        Description

        Identificador del tipo de detalle. Uno de: discount additional vatDevolutionBase shipping handlingFee insurance giftWrap subtotal fee tip airline interests

      • Name
        amount
        Type
        number
        is optional
        Description

        Monto total del detalle

        EJ: 200

Solicitud

POST
/api/reverse
curl -X "POST" https://checkout-test.placetopay.com/api/session/000000 \
-H "Content-Type: application/json" \
-d '{
    "auth": {
        "login": "c51ce410c124a10e0db5e4b97fc2af39",
        "tranKey": "VQOcRcVH2DfL6Y4B4SaK6yhoH/VOUveZ3xT16OQnvxE=",
        "nonce": "NjE0OWVkODgwYjNhNw==",
        "seed": "2021-09-21T09:34:48-05:00"
    },
    "internalReference": 1
}'

Respuesta

  • Name
    status
    Type
    Status
    is optional
    Description

    Estructura que contiene la información de la respuesta sobre una solicitud o pago, e informa el estado actual de la misma.

    • Name
      status
      Type
      string
      is optional
      Description

      Estado de una petición o pago

    • Name
      reason
      Type
      string|number|null
      is optional
      Description

      Código del motivo proporcionado.

    • Name
      message
      Type
      string|null
      is optional
      Description

      Descripción del código de razón.

    • Name
      date
      Type
      string
      is optional
      Description

      Fecha y hora en que se genera el estado de pago.

  • Name
    payment
    Type
    PaymentResponse
    is optional
    Description
    • Name
      status
      Type
      Status
      is optional
      Description

      Estructura que contiene la información de la respuesta sobre una solicitud o pago, e informa el estado actual de la misma.

      • Name
        status
        Type
        string
        is optional
        Description

        Estado de una petición o pago

      • Name
        reason
        Type
        string|number|null
        is optional
        Description

        Código del motivo proporcionado.

      • Name
        message
        Type
        string|null
        is optional
        Description

        Descripción del código de razón.

      • Name
        date
        Type
        string
        is optional
        Description

        Fecha y hora en que se genera el estado de pago.

    • Name
      internalReference
      Type
      string
      is optional
      Description
    • Name
      paymentMethod
      Type
      string
      is optional
      Description
    • Name
      paymentMethodName
      Type
      string
      is optional
      Description
    • Name
      issuerName
      Type
      string
      is optional
      Description
    • Name
      amount
      Type
      AmountConversion
      is optional
      Description

      Estructura para definir el factor de conversión y los valores.

      • Name
        from
        Type
        AmountBase
        is optional
        Description

        Estructura que representa una cantidad que define la moneda y el total.

        • Name
          currency
          Type
          string
          is optional
          Description

          Moneda acorde al ISO 4217 (alphabetic code).

        • Name
          total
          Type
          number|string
          is optional
          Description

          Valor total.

      • Name
        to
        Type
        AmountBase
        is optional
        Description

        Estructura que representa una cantidad que define la moneda y el total.

        • Name
          currency
          Type
          string
          is optional
          Description

          Moneda acorde al ISO 4217 (alphabetic code).

        • Name
          total
          Type
          number|string
          is optional
          Description

          Valor total.

      • Name
        factor
        Type
        number|string
        is optional
        Description

        Factor de conversión

    • Name
      authorization
      Type
      string
      is optional
      Description
    • Name
      reference
      Type
      string
      is optional
      Description
    • Name
      franchise
      Type
      string
      is optional
      Description
    • Name
      refunded
      Type
      boolean
      is optional
      Description
    • Name
      processorFields
      Type
      PaymentResponse
      is optional
      Description
      • Name
        keyword
        Type
        string
        is optional
        Description
      • Name
        value
        Type
        string|object|integer|array
        is optional
        Description
      • Name
        displayOn
        Type
        string
        is optional
        Description
    • Name
      receipt
      Type
      string
      is optional
      Description

Respuesta

{
    "status": {
        "status": "APPROVED",
        "reason": "00",
        "message": "Aprobada",
        "date": "2021-12-07T16:01:19-05:00"
    },
    "payment": {
        "status": {
        "status": "APPROVED",
        "reason": "00",
        "message": "Aprobada",
        "date": "2021-12-07T16:01:18-05:00"
        },
        "internalReference": 1,
        "paymentMethod": "visa",
        "paymentMethodName": "Visa",
        "issuerName": "JPMORGAN CHASE BANK, N.A.",
        "amount": {
        "from": {
            "currency": "USD",
            "total": 100
        },
        "to": {
            "currency": "USD",
            "total": 100
        },
        "factor": 1
        },
        "authorization": "123456",
        "reference": "12345",
        "receipt": "230955511860",
        "franchise": "PS_VS",
        "refunded": false,
        "processorFields": [
        {
            "keyword": "merchantCode",
            "value": "1465675",
            "displayOn": "none"
        },
        {
            "keyword": "terminalNumber",
            "value": "00990099",
            "displayOn": "none"
        },
        {
            "keyword": "credit",
            "value": {
            "code": "1",
            "type": "00",
            "groupCode": "C",
            "installments": 1
            },
            "displayOn": "none"
        },
        {
            "keyword": "totalAmount",
            "value": 52,
            "displayOn": "none"
        },
        {
            "keyword": "interestAmount",
            "value": 0,
            "displayOn": "none"
        },
        {
            "keyword": "installmentAmount",
            "value": 0,
            "displayOn": "none"
        },
        {
            "keyword": "iceAmount",
            "value": 0,
            "displayOn": "none"
        },
        {
            "keyword": "bin",
            "value": "411111",
            "displayOn": "none"
        },
        {
            "keyword": "expiration",
            "value": "1223",
            "displayOn": "none"
        },
        {
            "keyword": "lastDigits",
            "value": "1111",
            "displayOn": "none"
        },
        {
            "keyword": "id",
            "value": "a10fe0690cfe557283310ba90746e159",
            "displayOn": "none"
        },
        {
            "keyword": "b24",
            "value": "00",
            "displayOn": "none"
        }
        ]
    }
}
POST/api/transaction

Acciones de transacción

Permite realizar operaciones básicas de preauthorización como checkout, reauthorization, (No aplica para Puerto Rico) por otro lado también permite revertir un pago aprobado con el código de referencia interna reverse.

Solicitud

  • Name
    auth
    Type
    Authentication
    is Required
    REQUIRED
    Description

    La autenticación del sitio. Ver más en Autenticación

    • Name
      login
      Type
      string
      is optional
      Description

      Identificador del sitio.

    • Name
      tranKey
      Type
      string
      is optional
      Description

      Credencial tranKey generado.
      Ver más en Autenticación

    • Name
      nonce
      Type
      string
      is optional
      Description

      Valor aleatorio para cada solicitud codificado en Base64.

    • Name
      seed
      Type
      string
      is optional
      Description

      Fecha actual, la cual se genera en formato ISO 8601.

  • Name
    action
    Type
    string
    is Required
    REQUIRED
    Description

    Tipo de operación a realizar sobre la transacción

    reverse para reversar una transacción.
    reauthorization para modificar una transacción de checkin.
    checkout para cerrar y cobrar una transacción de checkin.

  • Name
    internalReference
    Type
    integer
    is Required
    REQUIRED
    Description

    Referencia interna única de la transacción

    EJ: 543423

  • Name
    amount
    Type
    Amount
    is optional
    Description

    Información del monto a cobrar

    • Name
      currency
      Type
      string
      is optional
      Description

      Código alfabético de la moneda a usar (ISO 4217 alpha code)
      EJ: USD

    • Name
      total
      Type
      number
      is optional
      Description

      Valor total en la moneda base indicada
      EJ: 1000 equivalen a Mil dolares

    • Name
      taxes
      Type
      array[Taxes]
      is optional
      Description

      Estructura para definir impuestos en el proceso de pago.

      • Name
        kind
        Type
        string
        is optional
        Description

        Identificador del tipo de impuesto

        Uno de: valueAddedTax exciseDuty ice airportTax stateTax reducedStateTax municipalTax.

      • Name
        amount
        Type
        number
        is optional
        Description

        Monto total del impuesto
        EJ: 200

      • Name
        base
        Type
        number
        is optional
        Description

        Monto base sobre el cual se calcula el impuesto
        EJ: 1000

    • Name
      details
      Type
      array[Details]
      is optional
      Description

      Estructura para definir detalles adicionales del monto en el proceso de pago.

      • Name
        kind
        Type
        string
        is optional
        Description

        Identificador del tipo de detalle. Uno de: discount additional vatDevolutionBase shipping handlingFee insurance giftWrap subtotal fee tip airline interests

      • Name
        amount
        Type
        number
        is optional
        Description

        Monto total del detalle

        EJ: 200

Solicitud

POST
/api/transaction
curl -X "POST" https://checkout-test.placetopay.com/api/transaction \
    -H "Content-Type: application/json" \
    -d "{
        "auth": {
            "login": "c51ce410c124a10e0db5e4b97fc2af39",
            "tranKey": "VQOcRcVH2DfL6Y4B4SaK6yhoH/VOUveZ3xT16OQnvxE=",
            "nonce": "NjE0OWVkODgwYjNhNw==",
            "seed": "2021-09-21T09:34:48-05:00"
        },
        "internalReference": 640,
        "amount": {
            "currency": "USD",
            "total": "500"
        },
        "action": "checkout"
    }"

Respuesta

  • Name
    reference
    Type
    string
    is Required
    REQUIRED
    Description

    Referencia única del pago. Máximo de 32 caracteres
    Ej: PAYMENT_0001_ABC

  • Name
    description
    Type
    string
    is Required
    REQUIRED
    Description

    Descripción del proceso a realizar
    EJ: Consumo mes de Mayo

  • Name
    amount
    Type
    Amount
    is Required
    REQUIRED
    Description

    Información del monto a cobrar

    • Name
      currency
      Type
      string
      is optional
      Description

      Código alfabético de la moneda a usar (ISO 4217 alpha code)
      EJ: USD

    • Name
      total
      Type
      number
      is optional
      Description

      Valor total en la moneda base indicada
      EJ: 1000 equivalen a Mil dolares

    • Name
      taxes
      Type
      array[Taxes]
      is optional
      Description

      Estructura para definir impuestos en el proceso de pago.

      • Name
        kind
        Type
        string
        is optional
        Description

        Identificador del tipo de impuesto

        Uno de: valueAddedTax exciseDuty ice airportTax stateTax reducedStateTax municipalTax.

      • Name
        amount
        Type
        number
        is optional
        Description

        Monto total del impuesto
        EJ: 200

      • Name
        base
        Type
        number
        is optional
        Description

        Monto base sobre el cual se calcula el impuesto
        EJ: 1000

    • Name
      details
      Type
      array[Details]
      is optional
      Description

      Estructura para definir detalles adicionales del monto en el proceso de pago.

      • Name
        kind
        Type
        string
        is optional
        Description

        Identificador del tipo de detalle. Uno de: discount additional vatDevolutionBase shipping handlingFee insurance giftWrap subtotal fee tip airline interests

      • Name
        amount
        Type
        number
        is optional
        Description

        Monto total del detalle

        EJ: 200

  • Name
    allowPartial
    Type
    boolean
    is optional
    Description

    Define si el monto a ser cobrado puede ser pagado en varias transacciones. Cuando es true el usuario podrá completar el pago en varias transacciones.

  • Name
    shipping
    Type
    Person
    is optional
    Description

    Estructura para relacionar información de envío.

    • Name
      document
      Type
      string
      is optional
      Description

      Documento de identidad

      Ej: 1017111222

    • Name
      documentType
      Type
      string
      is optional
      Description

      Identificador del tipo de documento. Ver opciones en Tipos de documento

      EJ: CC para "Cédula de Ciudadanía" en Colombia.

    • Name
      name
      Type
      string
      is optional
      Description

      Nombre de la persona o empresa

      EJ: Juan José

    • Name
      surname
      Type
      string
      is optional
      Description

      Apellido de la persona. No aplica cuando el tipo de documento corresponde al de una empresa

      EJ: Peréz Pinzon

    • Name
      company
      Type
      string
      is optional
      Description

      Nombre de la compañia a la que pertenece la persona

      EJ: Placetopay

    • Name
      email
      Type
      string
      is optional
      Description

      Correo eléctronico del usuario o empresa

      EJ: [email protected]

    • Name
      mobile
      Type
      string
      is optional
      Description

      Número de teléfono del usuario o empresa

      EJ: +573214445566

    • Name
      address
      Type
      object
      is optional
      Description

      Estructura para anexar información del domicilio o dirección

      • Name
        country
        Type
        string
        is optional
        Description

        País del domicilio

        EJ: Colombia

      • Name
        state
        Type
        string
        is optional
        Description

        Departamento del domicilio

        EJ: Antioquia

      • Name
        city
        Type
        string
        is optional
        Description

        Ciudad del domicilio

        EJ: Medellín

      • Name
        postalCode
        Type
        string
        is optional
        Description

        Código postal del domicilio

        EJ: 050012

      • Name
        street
        Type
        string
        is optional
        Description

        Dirección del domicilio

        EJ: Calle 12 #33a-12, Apto 101

      • Name
        phone
        Type
        string
        is optional
        Description

        Número telefónico del domicilio

        EJ: +573214445566

  • Name
    items
    Type
    array[Item]
    is optional
    Description

    Estructura para relacionar productos o artículos en el proceso.

    • Name
      sku
      Type
      string
      is optional
      Description

      Identificador SKU del artículo.
      EJ: SKU-12345

    • Name
      name
      Type
      string
      is optional
      Description

      Nombre del artículo.
      EJ: Manta de lana

    • Name
      category
      Type
      string
      is optional
      Description

      Categoría del artículo. Uno de: digital physical

    • Name
      qty
      Type
      number
      is optional
      Description

      Cantidad de artículos de este tipo.
      EJ: 23

    • Name
      price
      Type
      number
      is optional
      Description

      Costo total del artículo.
      EJ: 1400

    • Name
      tax
      Type
      number
      is optional
      Description

      Monto en impuestos del artículo.
      EJ: 100

  • Name
    fields
    Type
    array[NameValuePair]
    is optional
    Description

    Estructura para relacionar información adicional en el proceso. Ver más en Campos Adicionales

    • Name
      keyword
      Type
      string
      is optional
      Description

      Identificador o índice del dato a anexar.
      EJ: cmsInvoiceId

    • Name
      value
      Type
      string|object|array|number|boolean
      is optional
      Description

      Valor del dato a anexar.
      EJ: ID_2233

    • Name
      displayOn
      Type
      string
      is optional
      Description

      Indica en qué condiciones se muestra el dato anexo. Ver más en Campos Adicionales

      Uno de: none, payment, receipt, both, approved.

  • Name
    recurring
    Type
    object
    is optional
    Description

    Estructura para indicar la frecuencia de un cobro recurrente.

    • Name
      periodicity
      Type
      string
      is optional
      Description

      Periodicidad del cobro
      D Día, M Mes, Y Año

    • Name
      interval
      Type
      number
      is optional
      Description

      Intervalo asociado a la periodicidad
      EJ: 15 para días.

    • Name
      nextPayment
      Type
      string
      is optional
      Description

      Fecha del próximo pago
      EJ: 2019-08-24

    • Name
      maxPeriods
      Type
      number
      is optional
      Description

      Número máximo de periodos. Usar -1 en caso de que no haya límite
      EJ: 12 para máximo 12 cobros

    • Name
      dueDate
      Type
      string
      is optional
      Description

      Fecha de vencimiento de la recurrencia
      EJ: 2019-09-24

    • Name
      notificationUrl
      Type
      string
      is optional
      Description

      URL en el que el servicio notificará cada vez que se haga un cobro
      EJ: https://merchant.com/notification

  • Name
    subscribe
    Type
    boolean
    is optional
    Description

    Cuando se envía true, se genera una sesión de pago con suscripción.

    En el proceso de pago, el usuario puede elegir si quiere o no guardar su medio de pago para que sea usado en futuros cobros.

  • Name
    dispersion
    Type
    array[DispersionDetail]
    is optional
    Description

    Cuando se define, se genera una sesión de pago con dispersión. El pago generado puede ser dividido en diferentes destinos según las condiciones dadas.

    • Name
      amount
      Type
      Amount
      is optional
      Description

      Monto a "dispersar" en este destino.

      • Name
        currency
        Type
        string
        is optional
        Description

        Código alfabético de la moneda a usar (ISO 4217 alpha code)
        EJ: USD

      • Name
        total
        Type
        number
        is optional
        Description

        Valor total en la moneda base indicada
        EJ: 1000 equivalen a Mil dolares

      • Name
        taxes
        Type
        array[Taxes]
        is optional
        Description

        Estructura para definir impuestos en el proceso de pago.

        • Name
          kind
          Type
          string
          is optional
          Description

          Identificador del tipo de impuesto

          Uno de: valueAddedTax exciseDuty ice airportTax stateTax reducedStateTax municipalTax.

        • Name
          amount
          Type
          number
          is optional
          Description

          Monto total del impuesto
          EJ: 200

        • Name
          base
          Type
          number
          is optional
          Description

          Monto base sobre el cual se calcula el impuesto
          EJ: 1000

      • Name
        details
        Type
        array[Details]
        is optional
        Description

        Estructura para definir detalles adicionales del monto en el proceso de pago.

        • Name
          kind
          Type
          string
          is optional
          Description

          Identificador del tipo de detalle. Uno de: discount additional vatDevolutionBase shipping handlingFee insurance giftWrap subtotal fee tip airline interests

        • Name
          amount
          Type
          number
          is optional
          Description

          Monto total del detalle

          EJ: 200

    • Name
      agreement
      Type
      string|number
      is optional
      Description

      Id del destino de este monto. Puede ser el id de un sitio.

      EJ: 122

    • Name
      agreementType
      Type
      string
      is optional
      Description

      Tipo de destino de este monto.
      MERCHANT para sitios, AIRLINE para aerolineas.

  • Name
    modifiers
    Type
    array[Modifiers]
    is optional
    Description

    Estructura para definir modificadores en el cobro.

    Aplica para leyes de impuestos en paises especificos.

    • Name
      type
      Type
      string
      is optional
      Description

      Identificador del tipo de modificador.
      Sólo FEDERAL_GOVERMENT es soportado actualmente.

    • Name
      code
      Type
      number
      is optional
      Description

      Código del modificador.

      Para FEDERAL_GOVERMENT representa el número de ley para descuento.
      17934 Servicios Gastronómicos
      18083 IMESI Brasil - Argentina
      19210 Inclusión Financiera
      18910 Asignaciones Familiares
      18999 Reintegro Inmobiliarias

    • Name
      additional
      Type
      object
      is optional
      Description

      Estructura para anexar información al modificador

      • Name
        invoice
        Type
        string
        is optional
        Description

        Requerido cuando modifiers.[].type es FEDERAL_GOVERMENT. Indica el número de factura.

        EJ: 123456789


Respuesta

{
    "reference": "12345",
    "description": "Prueba de pago",
    "amount": {
        "currency": "COP",
        "total": 2000,
        "taxes": [
        {
            "kind": "valueAddedTax",
            "amount": 1000,
            "base": 0
        }
        ],
        "details": [
        {
            "kind": "discount",
            "amount": 1000
        }
        ]
    },
    "allowPartial": false,
    "shipping": {
        "document": "1122334455",
        "documentType": "CC",
        "name": "John",
        "surname": "Doe",
        "company": "Evertec",
        "email": "[email protected]",
        "mobile": "+5731111111111",
        "address": {
        "street": "Calle falsa 123",
        "city": "Medellín",
        "state": "Poblado",
        "postalCode": "55555",
        "country": "Colombia",
        "phone": "+573111111111"
        }
    },
    "items": [
        {
        "sku": "12345",
        "name": "product_1",
        "category": "physical",
        "qty": "1",
        "price": 1000,
        "tax": 0
        }
    ],
    "fields": [
        {
        "keyword": "_test_field_value_",
        "value": "_test_field_",
        "displayOn": "approved"
        }
    ],
    "recurring": {
        "periodicity": "D",
        "interval": "1",
        "nextPayment": "2019-08-24",
        "maxPeriods": 1,
        "dueDate ": "2019-09-24",
        "notificationUrl ": "https://checkout.placetopay.com"
    },
    "subscribe": false,
    "dispersion": [
        {
        "agreement": "1299",
        "agreementType": "MERCHANT",
        "amount": {
            "currency": "USD",
            "total": 200
        }
        }
    ],
    "modifiers": [
        {
        "type": "FEDERAL_GOVERNMENT",
        "code": 17934,
        "additional": {
            "invoice": "123345"
        }
        }
    ]
}