Skip to main content

Documentación

Pago con Tarjeta con Verificación 3DS

Un emisor de tarjetas puede requerir que un cliente en su sitio de comercio electrónico realice un paso adicional de seguridad: la verificación three-domain secure (3DS).

3DS es un protocolo para verificar la identidad en transacciones con tarjeta no presente.Su cliente es redirigido a un sitio web independiente con instrucciones para completar la verificación 3DS. Cuando la transacción con tarjeta se completa, el sitio web de 3DS redirige al cliente a una URL (que usted proporciona) indicando éxito o fallo, y notifica a Rapyd.Rapyd luego actualiza el backend de su sitio web.

Los beneficios comunes incluyen:

  • Un proceso de pago más fácil y rápido da como resultado una mejor experiencia de checkout para su cliente.

  • Las responsabilidades derivadas de contracargos se transfieren del comercio al emisor.

  • Reduce el riesgo de fraude y hace que los pagos sean más seguros.

  • No existen costos adicionales por el paso extra de verificación 3DS, que proporciona mayor seguridad para sus transacciones.

Certificación PCI

Solo los clientes con certificación PCI-DSS pueden manejar información de identificación personal de tarjetas. Este método está disponible para los comercios que han firmado un acuerdo especial con Rapyd.

Proceso de pago con tarjeta

La siguiente captura de pantalla representa un proceso de pago con tarjeta con SG (Singapur) y SGD (Dólar de Singapur) como país y moneda, según se describe en Encontrar métodos de pago disponibles.

  1. Ingrese los datos de la tarjeta.

  2. Haga clic en Realizar su pedido.

    64808358d207a.png

  3. Complete la verificación 3DS.

    6480835babcf5.png

  4. Redirección a la página de pago exitoso.

Flujo de pagos con tarjeta con verificación 3DS

La forma de encontrar los métodos específicos de pago con tarjeta que aceptará y los campos requeridos correspondientes que los clientes deben completar se describe en Cómo funciona.

Paso 1: Proceso de Pago con Tarjeta con Verificación 3DS
cards-3ds-process.jpg

  1. El cliente completa el pago con tarjeta en el checkout.

  2. Usted envía a Rapyd la solicitud de pago 3DS con el ID del cliente que comienza con cus_.

  3. Rapyd recibe la solicitud y redirige al cliente a la URL de verificación 3DS.

  4. Usted muestra la URL de 3DS al cliente.

Paso 2: Proceso de Pago con Tarjeta 3DS
card-3ds-payment-process.jpg

  1. El cliente completa la verificación 3DS del pago con tarjeta.

  2. El sitio web de 3DS redirige al cliente a una URL de éxito o error.

  3. Rapyd procesa el pago y envía la respuesta.

  4. Usted muestra la página de compra exitosa.

Secuencias de Mensajes de Pago con Tarjeta con Verificación 3DS

Los siguientes diagramas de secuencia de mensajes describen cómo se intercambia la información entre Rapyd, el comercio, los clientes del comercio y la red de tarjetas.

Pago con Tarjeta con Verificación 3DS - Éxito

card-payment-with-3ds-authentication---success.svg

Pago con Tarjeta con Verificación 3DS - Fallo

payment-with-3ds-verification---verification-failure.svg
Cómo Funcionan los Pagos con Tarjeta con 3DS

Comportamiento Especial de Pruebas en Sandbox

Para usar el Sandbox y simular un pago que requiere autenticación 3DS, configure el valor de amount entre 1000,00 y 1999.99.

Encontrar los métodos de pago disponibles

Capa 3DS para tarjetas

La capa 3DS no está disponible en todas las regiones. Se activa automáticamente cuando un mandato regulatorio, como PSD2, lo requiere.

Para obtener más detalles sobre cómo prevenir transacciones fraudulentas, consulte Rapyd Protect.

Verifique qué métodos de pago con tarjeta se aceptan en el país del cliente.Para hacerlo, utilice Listar métodos de pago por país con los siguientes parámetros:

Descripción de los Parámetros de Consulta

Parámetro de consulta

Descripción

país

Ingrese SG como el código del país.

moneda

Ingrese SGD como el código de la moneda.

Solicitud de listado de métodos de pago por país

Solicitud para obtener una lista de todos los métodos de pago disponibles en SG.

    • Solicitud

      • // Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/country?country=SG&currency=SGD

// Message body absent

    • .NET Core

      • using System;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                string result = RapydApiRequestSample.Utilities.MakeRequest("GET", "/v1/payment_methods/country?country=SG&currency=SGD");

                Console.WriteLine(result);
            }
            catch (Exception e)
            {
                Console.WriteLine("Error completing request: " + e.Message);
            }
        }
    }
}

    • JavaScript

      • const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

async function main() {
  try {
    const result = await makeRequest('GET', '/v1/payment_methods/country?country=SG&currency=SGD');

    console.log(result);
  } catch (error) {
    console.error('Error completing request', error);
  }
}

    • PHP

      • <?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/<path-to-your-utility-file>/utilities.php";
include($path);

try {
    $object = make_request('get', '/v1/payment_methods/country?country=SG&currency=SGD');
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>

    • Python

      • from pprint import pprint

from utilities import make_request

country = 'SG'
currency = 'SGD'
results = make_request(method='get', path=f'/v1/payment_methods/country?country={country}&currency={currency}')
pprint(results)
Respuesta de listado de métodos de pago por país

List Payment Methods by Country describe los campos incluidos en la respuesta.

    • Respuesta

      • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "cfa35a73-aa0b-4e7e-839c-4c3b6149edd7"
    },
    "data": [{
            "type": "sg_debit_cup_card",
            "name": "Union Pay Debit",
            "category": "card",
            "image": "https://iconslib.rapyd.net/checkout/sg_debit_cup_card.png",
            "country": "sg",
            "payment_flow_type": "card",
            "currencies": [
                "SGD"
            ],
            "status": 1,
            "is_cancelable": false,
            "payment_options": [{
                    "name": "customer",
                    "type": "customer",
                    "regex": "",
                    "description": "make sure a customer was created with first_name, last_name and email",
                    "is_required": true,
                    "is_updatable": false
                }
            ],
            "is_expirable": true,
            "is_online": false,
            "minimum_expiration_seconds": 600,
            "maximum_expiration_seconds": 604800
        }
    ]
}

La sección datos de la respuesta muestra que una tarjeta Visa es un método de pago aceptable.

Respuesta del listado de métodos de pago

Una respuesta completa de la API enumera múltiples métodos de pago.

Obtención de los campos requeridos para el método de pago

Debe identificar qué campos son necesarios completar para el método de pago.Para hacerlo, utilice Obtener campos requeridos del método de pago con el siguiente parámetro:

Descripción de los parámetros de ruta

Parámetro de ruta

Descripción

tipo

Ingrese sg_debit_cup_card como el tipo de método de pago.

Solicitud de obtención de los campos requeridos del método de pago

Solicitud para obtener el conjunto de campos requeridos para una tarjeta Visa.

    • Solicitud

      • // Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/sg_debit_cup_card/required_fields

// Message body absent

    • .NET Core

      • using System;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                string result = RapydApiRequestSample.Utilities.MakeRequest("GET", "/v1/payment_methods/sg_debit_cup_card/required_fields");

                Console.WriteLine(result);
            }
            catch (Exception e)
            {
                Console.WriteLine("Error completing request: " + e.Message);
            }
        }
    }
}

    • JavaScript

      • const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

async function main() {
  try {
    const result = await makeRequest('GET', '/v1/payment_methods/sg_debit_cup_card/required_fields');

    console.log(result);
  } catch (error) {
    console.error('Error completing request', error);
  }
}

    • PHP

      • <?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/<path-to-your-utility-file>/utilities.php";
include($path);

try {
    $object = make_request('get', '/v1/payment_methods/sg_debit_cup_card/required_fields');
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>

    • Python

      • from pprint import pprint

from utilities import make_request

payment_method = 'sg_debit_cup_card'
results = make_request(method='get', path=f'/v1/payment_methods/{payment_method}/required_fields')
pprint(results)
Respuesta de obtención de los campos requeridos del método de pago

Get Payment Method Required Fields describe los campos incluidos en la respuesta.

    • Respuesta

      • {
    “status”: {
        “error_code”: “”,
        “status”: “SUCCESS”,
        “message”: “”,
        “response_code”: “”,
        “operation_id”: “3b7a2391-6612-478e-b79e-38d7f8d33ff9”
    },
    “data”: {
        “type”: “sg_debit_cup_card”,
        “fields”: [
            {
                “name”: “name”,
                “type”: “string”,
                “regex”: “”,
                “is_required”: true,
                “instructions”: “card holder name”
            },
            {
                “name”: “number”,
                “type”: “string”,
                “regex”: “”,
                “is_required”: true,
                “instructions”: “card number”
            },
            {
                “name”: “expiration_month”,
                “type”: “string”,
                “regex”: “”,
                “is_required”: true,
                “instructions”: “expiration month as string, 01-12"
            },
            {
                “name”: “expiration_year”,
                “type”: “string”,
                “regex”: “”,
                “is_required”: true,
                “instructions”: “expiration year in to digits as string, 18-99”
            },
            {
                “name”: “cvv”,
                “type”: “string”,
                “regex”: “”,
                “is_required”: true,
                “instructions”: “card cvv”
            }
        ],
        “payment_method_options”: [
            {
                “name”: “3d_required”,
                “type”: “string”,
                “regex”: “”,
                “description”: “”,
                “is_required”: false,
                “is_updatable”: false
            }
        ],
        “payment_options”: [
            {
                “name”: “description”,
                “type”: “string”,
                “regex”: “”,
                “description”: “the description field must be filled in.“,
                “is_required”: true,
                “is_updatable”: false
            },
            {
                “name”: “complete_payment_url”,
                “type”: “string”,
                “regex”: “”,
                “description”: “the complete_payment_url field must be filled in.“,
                “is_required”: true,
                “is_updatable”: false
            },
            {
                “name”: “error_payment_url”,
                “type”: “string”,
                “regex”: “”,
                “description”: “the error_payment_url field must be filled in.“,
                “is_required”: true,
                “is_updatable”: false
            }
        ],
        “minimum_expiration_seconds”: 600,
        “maximum_expiration_seconds”: 604800
    }
}

La respuesta muestra que, para una tarjeta de débito UnionPay SG, es obligatorio proporcionar los siguientes campos:

  • nombre

  • número

  • mes_expiración

  • año_expiración

  • cvv

Asegúrese de que su cliente complete todos estos campos.

Procesamiento del pago

En este punto, su cliente debe haber completado lo siguiente:

  • Haber seleccionado Visa como opción de pago.

  • Haber completado los campos requeridos para pagar con tarjeta.

Cuando su cliente confirme el pago con tarjeta, solicite a Rapyd que procese el pago.

Para ello, deberá llamar a Crear pago con los siguientes parámetros:

Descripción de los parámetros del cuerpo

Parámetro del cuerpo

Descripción

método_pago

Ingrese un objeto con los siguientes campos:

  • tipo - sg_debit_cup_card

  • campos - Ingrese un objeto con los siguientes campos:

    • nombre - nombre del titular de la tarjeta

    • número - 4111111111111111

    • mes_expiración - 12

    • año_expiración - 29

    • cvv - 737

monto

Ingrese 1.001 como el monto del pago.

moneda

Ingrese SGD como el código de la moneda.

captura

Ingrese verdadero como el valor. Esto indica a Rapyd que procese el pago y capture los fondos lo antes posible.

error_payment_url

Reemplace https://error.example.net en el ejemplo con la URL real de su sitio web a la que desea que el sitio 3DS redirija al cliente si el pago falla.

complete_payment_url

Reemplace https://complete.example.net en el ejemplo con la URL real de su sitio web a la que desea que el sitio 3DS redirija al cliente si el pago se realiza correctamente.

opciones_método_de_pago

«3d_required»: «verdadero»

Solicitud de creación de pago

Solicite a Rapyd que procese el pago con tarjeta de su cliente por un monto de 1,001 SGD.

    • Solicitud

      • // Request URL: POST https://sandboxapi.rapyd.net/v1/payments

// Message body: 
{
   "amount": 1001,
   "currency": "SGD",
   "payment_method": {
       "type":"sg_debit_cup_card",
       "fields": {
           "number": "4111111111111111",
           "expiration_month": "12",
           "expiration_year": "29",
           "cvv": "737",
           "name":"Cardholder Name",
       }
   },
     "payment_method_options": {
        "3d_required": "true"
    },
   "error_payment_url": "https://error.example.net",
   "complete_payment_url": "https://complete.example.net",
   "capture": true
}

    • .NET Core

      • using System;
using System.Text.Json;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                var requestObj = new
                {
                    amount = 1001,
                    currency = "SGD",
                    payment_method = new
                    {
                        type = "sg_debit_cup_card",
                        fields = new
                        {
                            number = "4111111111111111",
                            expiration_month = "12",
                            expiration_year = "29",
                            cvv = "737",
                            name = "Cardholder Name"
                        }
                    },
                    error_payment_url = "https:error.example.net",
                    complete_payment_url = "https:complete.example.net",
                    payment_method_options = new
                    {
                         3d_required = true
                },
                    capture = true
                };

                string request = JsonSerializer.Serialize(requestObj);

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/payments", request);

                Console.WriteLine(result);
            }
            catch (Exception e)
            {
                Console.WriteLine("Error completing request: " + e.Message);
            }
        }
    }

    • JavaScript

      • const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

async function main() {
  try {
    const body = {
      amount: 1001,
      currency: 'SGD',
      payment_method: {
        type: 'sg_debit_cup_card',
        fields: {
          number: '4111111111111111',
          expiration_month: '12',
          expiration_year: '29',
          cvv: '737',
          name: 'Cardholder Name'
        }
      },
      error_payment_url: 'https://error.example.net',
      complete_payment_url: 'https://complete.example.net',
      "payment_method_options": {        
        "3d_required": true    
    },
      capture: true
    };
    const result = await makeRequest('POST', '/v1/payments', body);

    console.log(result);
  } catch (error) {
    console.error('Error completing request', error);
  }
}

    • PHP

      • <?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/<path-to-your-utility-file>/utilities.php";
include($path);

$body = [
    'amount' => 1001,
    'currency' => 'SGD',
    'payment_method' => [
        'type' => 'sg_debit_cup_card',
        'fields' => [
            'number' => '4111111111111111',
            'expiration_month' => '12',
            'expiration_year' => '29'
            'cvv' => '737',
            'name' => 'Cardholder Name'
        ]
    ],
    'error_payment_url' => urldecode('https://error_example.net'),
    'complete_payment_url' => urldecode('https://complete_example.net') 
    'payment_method_options'=> [
            '3d_required => true
    ],
    'capture' => true
];

try {
    $object = make_request('post', '/v1/payments', $body);
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>

    • Python

      • const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

from pprint import pprint

from utilities import make_request

payment_body = {
    'amount': 1001,
    'currency': 'SGD',
    'payment_method': {
        'type': 'sg_debit_cup_card',
        'fields': {
            'number': '4111111111111111',
            'expiration_month': '10',
            'expiration_year': '29',
            'cvv': '123',
            'name': 'Cardholder Name'
        }
    },
    'error_payment_url': 'https://error_example.net',
    'complete_payment_url': 'https://complete_example.net',
    'payment_method_options': {
            '3d_required: true
    },
    'capture': true
}

results = make_request(method='post', path='/v1/payments', body=payment_body)
pprint(results)
Respuesta de creación de pago

Crear pago describe los campos incluidos en la respuesta.

    • Respuesta

      • {
   {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "74d80a88-90a0-44d7-b08f-31f2b2739eef"
    },
    "data": {
        "id": "payment_2bb5e3d9376663dbecb0086298ffc08c",
        "amount": 0,
        "original_amount": 1001,
        "is_partial": false,
        "currency_code": "SGD",
        "country_code": "SG",
        "status": "ACT",
        "description": "",
        "merchant_reference_id": "",
        "customer_token": "cus_56fe83bb28b1e36a9552d68dfa16e3ff",
        "payment_method": "card_0540e5a4c9b8a4fc6a85bb6c6731c423",
        "payment_method_data": {
            "id": "card_0540e5a4c9b8a4fc6a85bb6c6731c423",
            "type": "sg_debit_cup_card",
            "category": "card",
            "metadata": null,
            "image": "",
            "webhook_url": "",
            "supporting_documentation": "",
            "next_action": "3d_verification",
            "name": "Cardholder Name",
            "last4": "1111",
            "acs_check": "unchecked",
            "cvv_check": "unchecked",
            "bin_details": {
                "type": null,
                "brand": null,
                "level": null,
                "issuer": null,
                "country": null,
                "bin_number": "411111"
            },
            "expiration_year": "29",
            "expiration_month": "12",
            "fingerprint_token": "ocfp_2a694038316f52122bbbb3ae926cfda9"
        },
        "auth_code": null,
        "expiration": 1692306562,
        "captured": true,
        "refunded": false,
        "refunded_amount": 0,
        "receipt_email": "",
        "redirect_url": "https://sandboxcheckout.rapyd.net/3ds-payment?token=payment_2bb5e3d9376663dbecb0086298ffc08c",
        "complete_payment_url": "https://rapyd.net",
        "error_payment_url": "https://docs.rapyd.net",
        "receipt_number": "",
        "flow_type": "",
        "address": null,
        "statement_descriptor": "Test Business",
        "transaction_id": "",
        "created_at": 1691701762,
        "metadata": {},
        "failure_code": "",
        "failure_message": "",
        "paid": false,
        "paid_at": 0,
        "dispute": null,
        "refunds": null,
        "order": null,
        "outcome": null,
        "visual_codes": {},
        "textual_codes": {},
        "instructions": [],
        "ewallet_id": "ewallet_db4ad4a76278f94c4a83dd9b28b483ed",
        "ewallets": [
            {
                "ewallet_id": "ewallet_db4ad4a76278f94c4a83dd9b28b483ed",
                "amount": 1001,
                "percent": 100,
                "refunded_amount": 0
            }
        ],
        "payment_method_options": {
            "3d_required": true
        },
        "payment_method_type": "sg_debit_cup_card",
        "payment_method_type_category": "card",
        "fx_rate": 1,
        "merchant_requested_currency": null,
        "merchant_requested_amount": null,
        "fixed_side": "",
        "payment_fees": null,
        "invoice": "",
        "escrow": null,
        "group_payment": "",
        "cancel_reason": null,
        "initiation_type": "customer_present",
        "mid": "",
        "next_action": "3d_verification",
        "error_code": "",
        "remitter_information": {},
        "save_payment_method": true
    }
}

La sección datos de la respuesta muestra lo siguiente:

  • monto es 1001

  • moneda es SGD

  • A su cliente invitado se le asigna automáticamente un ID de cliente. Al método de pago se le asigna un ID de método de pago. Ambos identificadores son únicos para esta transacción.

  • capturado es verdadero - lo que indica que el pago con tarjeta se recaudará lo antes posible.

  • redireccionar_url es https://redirect.example.net, que es la URL a la que usted redirige a su cliente invitado para completar el proceso de pago.

  • pagado es falso y el estado es ACT (activo), lo que indica que aún se está esperando a que el cliente invitado finalice el proceso 3DS.

Recepción de la confirmación de pago

En este punto, usted ha redirigido al cliente a https://redirect.example.net, que es un sitio de verificación 3DS. Este sitio puede manejar la verificación 3DS por sí mismo o redirigir al cliente al sitio web de su propia tarjeta. El cliente sigue las instrucciones de autenticación que aparecen en la pantalla, lo que puede implicar copiar un número desde un correo electrónico o un SMS e ingresarlo en la página web. Cuando el proceso se completa correctamente, Rapyd le envía un webhook con los detalles de la transacción completada.

Vamos a echar un vistazo a Webhook de pago completado.

    • Webhook

      •   {
    "id": "wh_7f18c2b90892652fe7ff2cb7d0537732",
    "type": "PAYMENT_COMPLETED",
    "data": {
        "id": "payment_2bb5e3d9376663dbecb0086298ffc08c",
      
//      ...      
      
        "paid": true,
      
//      ...      
      
        "amount": 1001,
        "status": "CLO",
      
//      ...      
      
        "currency_code": "SGD",
      
//      ...      
      
        "customer_token": "cus_56fe83bb28b1e36a9552d68dfa16e3ff",
        "payment_method": "card_0540e5a4c9b8a4fc6a85bb6c6731c423",
      
//      ...      
      
        "payment_method_type_category": "card"
    },
    "trigger_operation_id": "",
    "status": "NEW",
    "created_at": 1691701778
}

La sección datos del webhook muestra lo siguiente:

  • pagado es cierto y estado es CLO (cerrado), lo que indica que el dinero se ha pagado.

  • cantidad es 1.001

  • código_moneda es SGD

  • El token_del_cliente y método_pago son los mismos que en la respuesta de creación de pago.

En esta sección:

A protocol that provides increased security for card-not-present transactions. Rapyd supports version 2.2.

Money that is returned to the customer after the customer wins a dispute of a card or bank transaction.

Regulations developed for the payment card industry for data security and protection against fraud.

In Rapyd, the sandbox environment provides most of the functionality of the production environment, without using real money. Interested persons can use the sandbox to explore Rapyd's product offering or to test software integrations with Rapyd's API.

In the European Union (EU) and European Economic Area (EEA), legislation for protecting consumers and making payments more secure.