Least Cost Routing/
Integrate

Integrate Least Cost Routing

DOCSCURRENT

Last updated: Aug 15th, 5:54am

This page shows you how to integrate Least Cost Routing.

How it works

PayPal checks if the transaction is eligible for Least Cost Routing. For more information, see Eligibility.

  • If the transaction is eligible, it will be routed to debit networks through the Pay Secure Processor.
  • If the transaction is ineligible, the transaction will go through Visa or Mastercard through the First Data processor.

Note: There is no change in the checkout experience for buyers.

1. Tokenize your card

Make your card into a token. Tokenizing the card can happen with or without a billing address. The CVV field is also optional.

Query

    1mutation TokenizeCreditCard($input: TokenizeCreditCardInput!) {
    2    tokenizeCreditCard(input: $input) {
    3      paymentMethod {
    4        id
    5        legacyId
    6      }
    7    }
    8  }

    Variable

      1{
      2  "input": {
      3    "creditCard": {
      4      "number": "5208233085365191",
      5      "expirationYear": "2024",
      6      "expirationMonth": "12",
      7      "cvv": "123",
      8      "billingAddress": {
      9          "firstName": "John",
      10          "lastName":"Smith",
      11          "streetAddress": "500 Main St",
      12          "region":"CA",
      13          "postalCode": "95131",
      14          "countryCodeAlpha2":"US"
      15      }
      16    }
      17  }
      18}

      2. Create a transaction

      Make a transaction with your tokenized card details.

      Query

        1mutation chargePaymentMethod($input: ChargePaymentMethodInput!) {
        2  chargePaymentMethod(input: $input) {
        3    transaction {
        4      id,
        5      status,
        6      debitNetwork
        7    }
        8  }
        9}

        Variable

          1{
          2  "input": {
          3    "paymentMethodId": "cGF5bWVudG1ldGhvZF9jY19uM3BxZzIz",
          4    "transaction": {
          5      "amount": "1.00"
          6    }
          7  }
          8}

          Search for a transaction

          Least Cost Routing transactions can be searched by transaction ID or by the Least Cost Routing network that the transaction passed through.

          Query

            1query Search($input: TransactionSearchInput!) {
            2        search {
            3          transactions(input: $input) {
            4            pageInfo {
            5              hasNextPage
            6              hasPreviousPage
            7              startCursor
            8              endCursor
            9            }
            10            edges {
            11              node {
            12                id
            13                createdAt
            14                paymentInitiatedAt
            15                status
            16                source
            17                debitNetwork
            18                amount {
            19                  value
            20                  currencyIsoCode
            21                  currencyCode
            22                }
            23                merchantAccountId
            24                orderId
            25                customer {
            26                  id
            27                }
            28                disbursementDetails {
            29                  date
            30                  amount {
            31                    value
            32                    currencyIsoCode
            33                    currencyCode
            34                  }
            35                  exchangeRate
            36                  fundsHeld
            37                }
            38                riskData {
            39                  id
            40                  decision
            41                  deviceDataCaptured
            42                  fraudServiceProvider
            43                }
            44                facilitatorDetails {
            45                  oauthApplication {
            46                    clientId
            47                    name
            48                  }
            49                }
            50                statusHistory {
            51                  __typename
            52                  status
            53                  timestamp
            54                  source
            55                  terminal
            56                  amount {
            57                    value
            58                    currencyIsoCode
            59                    currencyCode
            60                  }
            61                  ... on AuthorizedEvent {
            62                    processorResponse {
            63                      legacyCode
            64                      message
            65                      cvvResponse
            66                      avsPostalCodeResponse
            67                      avsStreetAddressResponse
            68                      authorizationId
            69                    }
            70                    networkResponse {
            71                      code
            72                      message
            73                    }
            74                    riskDecision
            75                  }
            76                  ... on GatewayRejectedEvent {
            77                    gatewayRejectionReason
            78                    processorResponse {
            79                      cvvResponse
            80                      avsPostalCodeResponse
            81                      avsStreetAddressResponse
            82                      authorizationId
            83                    }
            84                    networkResponse {
            85                      code
            86                      message
            87                    }
            88                    riskDecision
            89                  }
            90                  ... on ProcessorDeclinedEvent {
            91                    declineType
            92                    processorResponse {
            93                      legacyCode
            94                      message
            95                      cvvResponse
            96                      avsPostalCodeResponse
            97                      avsStreetAddressResponse
            98                      authorizationId
            99                    }
            100                    networkResponse {
            101                      code
            102                      message
            103                    }
            104                  }
            105                  ... on FailedEvent {
            106                    processorResponse {
            107                      legacyCode
            108                      message
            109                      cvvResponse
            110                      avsPostalCodeResponse
            111                      avsStreetAddressResponse
            112                      authorizationId
            113                    }
            114                    networkResponse {
            115                      code
            116                      message
            117                    }
            118                    riskDecision
            119                  }
            120                  ... on SettlementDeclinedEvent {
            121                    processorResponse {
            122                      legacyCode
            123                      message
            124                    }
            125                  }
            126                  ... on SettlementPendingEvent {
            127                    processorResponse {
            128                      legacyCode
            129                      message
            130                    }
            131                  }
            132                }
            133                paymentMethodSnapshot {
            134                  __typename
            135                  ... on CreditCardDetails {
            136                    brand
            137                    brandCode
            138                    last4
            139                    expirationMonth
            140                    expirationYear
            141                    bin
            142                    binData {
            143                      prepaid
            144                      healthcare
            145                      debit
            146                      durbinRegulated
            147                      commercial
            148                      payroll
            149                      issuingBank
            150                      countryOfIssuance
            151                      productId
            152                    }
            153                    uniqueNumberIdentifier
            154                    cardholderName
            155                  }
            156                }
            157                customFields {
            158                  name
            159                  value
            160                }
            161                processorResponse {
            162                  legacyCode
            163                  message
            164                  avsPostalCodeResponse
            165                  avsStreetAddressResponse
            166                  cvvResponse
            167                }
            168              }
            169              cursor
            170            }
            171          }
            172        }
            173      }

            Variable

            Searching by Transaction ID

              1{
              2    "input": {
              3      "id": {
              4        "is": "dHJhbnNhY3Rpb25fbW5rZGFzMWc"
              5      }
              6    }
              7}

              Searching by Network

                1{
                2          "input": {
                3            "debitNetwork": {
                4              "is": "STAR"
                5            },
                6            "createdAt": {
                7            "greaterThanOrEqualTo": "2022-03-20T11:52:26+00:00",
                8            "lessThanOrEqualTo":"2022-03-30T11:52:26+00:00"
                9          }
                10          }
                11        }

                Reversing a transaction

                Reversal API can be called at any point after a transaction is made. Calling Reversal API within a 20-minute window on a transaction with the status "SUBMITTED_FOR_SETTLEMENT" will result in void. Calling Reversal API after a 20-minute window on a transaction with the status "SETTLED" or "SETTLING" will result in a refund.

                Query

                  1mutation ($input: ReverseTransactionInput!) {
                  2  reverseTransaction(input: $input) {
                  3    reversal {
                  4      __typename
                  5      ... on Transaction {
                  6        id
                  7        legacyId
                  8        createdAt
                  9        paymentMethodSnapshot {
                  10          __typename
                  11          ... on CreditCardDetails {
                  12            brandCode
                  13            last4
                  14            bin
                  15            expirationMonth
                  16            expirationYear
                  17          }
                  18          ... on UsBankAccountDetails {
                  19            accountType
                  20            ownershipType
                  21            bankName
                  22            last4
                  23            routingNumber
                  24            verified
                  25          }
                  26          ... on PayPalTransactionDetails {
                  27            payer {
                  28              billingAgreementId
                  29              email
                  30              payerId
                  31            }
                  32          }
                  33          ... on VenmoAccountDetails {
                  34            username
                  35            venmoUserId
                  36          }
                  37        }
                  38        amount {
                  39          value
                  40          currencyIsoCode
                  41        }
                  42        merchantAccountId
                  43        orderId
                  44        status
                  45        statusHistory {
                  46          __typename
                  47          status
                  48          timestamp
                  49          amount {
                  50            value
                  51            currencyIsoCode
                  52          }
                  53          source
                  54          terminal
                  55          ... on AuthorizedEvent {
                  56            processorResponse {
                  57              legacyCode
                  58              message
                  59              cvvResponse
                  60              avsPostalCodeResponse
                  61              avsStreetAddressResponse
                  62              authorizationId
                  63              additionalInformation
                  64            }
                  65            networkResponse {
                  66              code
                  67              message
                  68            }
                  69          }
                  70          ... on ProcessorDeclinedEvent {
                  71            declineType
                  72            processorResponse {
                  73              legacyCode
                  74              message
                  75              cvvResponse
                  76              avsPostalCodeResponse
                  77              avsStreetAddressResponse
                  78              authorizationId
                  79              additionalInformation
                  80            }
                  81            networkResponse {
                  82              code
                  83              message
                  84            }
                  85            riskDecision
                  86          }
                  87          ... on SettlementPendingEvent {
                  88            processorResponse {
                  89              legacyCode
                  90              message
                  91            }
                  92          }
                  93          ... on SettledEvent {
                  94            processorResponse {
                  95              legacyCode
                  96              message
                  97            }
                  98          }
                  99          ... on SettlementDeclinedEvent {
                  100            processorResponse {
                  101              legacyCode
                  102              message
                  103            }
                  104          }
                  105          ... on FailedEvent {
                  106            processorResponse {
                  107              legacyCode
                  108              message
                  109              cvvResponse
                  110              avsPostalCodeResponse
                  111              avsStreetAddressResponse
                  112              authorizationId
                  113              additionalInformation
                  114            }
                  115            networkResponse {
                  116              code
                  117              message
                  118            }
                  119            riskDecision
                  120          }
                  121          ... on GatewayRejectedEvent {
                  122            gatewayRejectionReason
                  123            processorResponse {
                  124              legacyCode
                  125              message
                  126              cvvResponse
                  127              avsPostalCodeResponse
                  128              avsStreetAddressResponse
                  129              authorizationId
                  130              additionalInformation
                  131            }
                  132            networkResponse {
                  133              code
                  134              message
                  135            }
                  136            riskDecision
                  137          }
                  138        }
                  139        source
                  140        paymentMethod {
                  141          id
                  142        }
                  143        channel
                  144      }
                  145      ... on Refund {
                  146        id
                  147        legacyId
                  148        createdAt
                  149        paymentMethodSnapshot {
                  150          __typename
                  151          ... on CreditCardDetails {
                  152            brandCode
                  153            last4
                  154            bin
                  155            expirationMonth
                  156            expirationYear
                  157          }
                  158          ... on UsBankAccountDetails {
                  159            accountType
                  160            ownershipType
                  161            bankName
                  162            last4
                  163            routingNumber
                  164            verified
                  165          }
                  166          ... on PayPalTransactionDetails {
                  167            payer {
                  168              billingAgreementId
                  169              email
                  170              payerId
                  171            }
                  172          }
                  173          ... on VenmoAccountDetails {
                  174            username
                  175            venmoUserId
                  176          }
                  177        }
                  178        amount {
                  179          value
                  180          currencyIsoCode
                  181        }
                  182        merchantAccountId
                  183        orderId
                  184        status
                  185        statusHistory {
                  186          __typename
                  187          status
                  188          timestamp
                  189          amount {
                  190            value
                  191            currencyIsoCode
                  192          }
                  193          source
                  194          terminal
                  195          ... on AuthorizedEvent {
                  196            processorResponse {
                  197              legacyCode
                  198              message
                  199              cvvResponse
                  200              avsPostalCodeResponse
                  201              avsStreetAddressResponse
                  202              authorizationId
                  203              additionalInformation
                  204            }
                  205            networkResponse {
                  206              code
                  207              message
                  208            }
                  209          }
                  210          ... on ProcessorDeclinedEvent {
                  211            declineType
                  212            processorResponse {
                  213              legacyCode
                  214              message
                  215              cvvResponse
                  216              avsPostalCodeResponse
                  217              avsStreetAddressResponse
                  218              authorizationId
                  219              additionalInformation
                  220            }
                  221            networkResponse {
                  222              code
                  223              message
                  224            }
                  225            riskDecision
                  226          }
                  227          ... on SettlementPendingEvent {
                  228            processorResponse {
                  229              legacyCode
                  230              message
                  231            }
                  232          }
                  233          ... on SettledEvent {
                  234            processorResponse {
                  235              legacyCode
                  236              message
                  237            }
                  238          }
                  239          ... on SettlementDeclinedEvent {
                  240            processorResponse {
                  241              legacyCode
                  242              message
                  243            }
                  244          }
                  245          ... on FailedEvent {
                  246            processorResponse {
                  247              legacyCode
                  248              message
                  249              cvvResponse
                  250              avsPostalCodeResponse
                  251              avsStreetAddressResponse
                  252              authorizationId
                  253              additionalInformation
                  254            }
                  255            networkResponse {
                  256              code
                  257              message
                  258            }
                  259            riskDecision
                  260          }
                  261          ... on GatewayRejectedEvent {
                  262            gatewayRejectionReason
                  263            processorResponse {
                  264              legacyCode
                  265              message
                  266              cvvResponse
                  267              avsPostalCodeResponse
                  268              avsStreetAddressResponse
                  269              authorizationId
                  270              additionalInformation
                  271            }
                  272            networkResponse {
                  273              code
                  274              message
                  275            }
                  276            riskDecision
                  277          }
                  278        }
                  279        source
                  280        paymentMethod {
                  281          id
                  282        }
                  283      }
                  284    }
                  285  }
                  286}

                  Variable

                    1{
                    2  "input": {
                    3    "transactionId": "dHJhbnNhY3Rpb25fMDJzY21wcW4"
                    4  }
                    5}

                    Test

                    The sandbox environment only accepts the below test credit card numbers to process Least Cost Routing transactions. While we use these test cards, the test biller account will need to be configured with the Least Cost Routing feature to get a debitNetwork=STAR on the API response. Transactions are routed to any one of the STAR, ACCEL, NYCE or PULSE debit networks based on the least cost routing. This depends on the transaction amount sent in the transaction sale request and the merchant category code of the merchant account.

                    5208233085365191(Master card) or 4070021557035923 (Visa)

                    When a transaction fails in the debit network, the transaction will be retried in the credit network such as Visa or Mastercard. The merchant account should have pinless retry debit enabled as the credit field and some retry configurations for the retry to happen.

                    If you want to retry a Least Cost Routing transaction in sandbox, the transaction amount will need to be set to 2046.

                    When the retry is successfully processed, the debitNetwork field will be null as the retry is not processed through the Least Cost Routing network.

                      1"transaction": {
                      2  "id": "5p4z558e",
                      3.
                      4.
                      5.
                      6

                      7"retriedTransactionId": "79cv9vpc", // this shows the parent transaction that failed initially
                      8 "retried": true,
                      9 "debitNetwork": null
                      10}

                      For a failed retry, the original transaction will show up with the original ID and all the retry IDs.

                        1"transaction": {
                        2 "id": "79cv9vpc",
                        3.
                        4.
                        5.
                        6"retryIds": [
                        7            "02scmpqn",
                        8            "5p4z558e"
                        9        ], 
                        10.
                        11.
                        12

                        13   "retried": true,
                        14}

                        Processing debit as credit

                        Optionally, we can send a transaction to be processed as credit to override the eligibility check and process the transaction through the Least Cost Routing network.

                        Query

                          1mutation chargePaymentMethod($input: ChargePaymentMethodInput!) {
                          2  chargePaymentMethod(input: $input) {
                          3    transaction {
                          4      id,
                          5      status,
                          6      debitNetwork   
                          7    }
                          8  }
                          9}

                          Variable

                            1{
                            2        "input": {
                            3          "paymentMethodId": "tokencc_bf_qcfgdt_68ypv9_hhz6kx_jzwrtp_7my",
                            4          "transaction": {
                            5            "amount": "10.00",
                            6            "merchantAccountId": "pgne15"
                            7          },
                            8          "options": {
                            9            "processDebitAsCredit": false
                            10          }
                            11    }
                            12}

                            Go live

                            To go live with the Least Cost Routing feature, contact your Technical Account Manager.

                            ReferencePayPal.comPrivacyCookiesSupportLegalContact

                            We currently use cookies to improve and customize your experience on our site. If you accept, we’ll also use marketing cookies to show you personalized ads. Manage your cookies and learn more.