spec release

json/BalancePlatformTransferNotification-v3.json

@@ -153,7 +153,7 @@
             "additionalProperties" : false,
             "properties" : {
                "city" : {
-                  "description" : "The name of the city.\n\nSupported characters: [a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ | and Space.",
+                  "description" : "The name of the city.\n\nSupported characters: **[a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ |** and Space.\n\n> Required when the `category` is **card**.\n",
                   "minLength" : 3,
                   "type" : "string"
                },
@@ -162,20 +162,20 @@
                   "type" : "string"
                },
                "line1" : {
-                  "description" : "First line of the street address.\n\nSupported characters: [a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ | and Space.",
+                  "description" : "The first line of the street address.\n\nSupported characters: **[a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ |** and Space.\n\n> Required when the `category` is **card**.\n",
                   "type" : "string"
                },
                "line2" : {
-                  "description" : "Second line of the street address.\n\nSupported characters: [a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ | and Space.",
+                  "description" : "The second line of the street address.\n\nSupported characters: **[a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ |** and Space.\n\n> Required when the `category` is **card**.\n",
                   "type" : "string"
                },
                "postalCode" : {
-                  "description" : "The postal code.\nMaximum length:\n* 5 digits for an address in the US.\n* 10 characters for an address in all other countries.\n\nSupported characters: [a-z] [A-Z] [0-9] and Space.\n",
+                  "description" : "The postal code.\nMaximum length:\n* 5 digits for an address in the US.\n* 10 characters for an address in all other countries.\n\nSupported characters: **[a-z] [A-Z] [0-9]** and Space.\n\n> Required for addresses in the US.\n",
                   "minLength" : 3,
                   "type" : "string"
                },
                "stateOrProvince" : {
-                  "description" : "   The two-letter ISO 3166-2 state or province code. For example, **CA** in the US or **ON** in Canada.\n   > Required for the US and Canada.\n",
+                  "description" : "   The two-letter ISO 3166-2 state or province code. For example, **CA** in the US or **ON** in Canada.\n\n   > Required for the US and Canada.\n",
                   "type" : "string"
                }
             },
@@ -1391,6 +1391,11 @@
                   },
                   "type" : "array"
                },
+               "externalReason" : {
+                  "x-addedInVersion" : "3",
+                  "description" : "The external reason of this transfer.",
+                  "$ref" : "#/components/schemas/ExternalReason"
+               },
                "id" : {
                   "description" : "The ID of the resource.",
                   "type" : "string"

json/BalancePlatformTransferNotification-v4.json

@@ -190,7 +190,7 @@
             "additionalProperties" : false,
             "properties" : {
                "city" : {
-                  "description" : "The name of the city.\n\nSupported characters: [a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ | and Space.",
+                  "description" : "The name of the city.\n\nSupported characters: **[a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ |** and Space.\n\n> Required when the `category` is **card**.\n",
                   "minLength" : 3,
                   "type" : "string"
                },
@@ -199,20 +199,20 @@
                   "type" : "string"
                },
                "line1" : {
-                  "description" : "First line of the street address.\n\nSupported characters: [a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ | and Space.",
+                  "description" : "The first line of the street address.\n\nSupported characters: **[a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ |** and Space.\n\n> Required when the `category` is **card**.\n",
                   "type" : "string"
                },
                "line2" : {
-                  "description" : "Second line of the street address.\n\nSupported characters: [a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ | and Space.",
+                  "description" : "The second line of the street address.\n\nSupported characters: **[a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ |** and Space.\n\n> Required when the `category` is **card**.\n",
                   "type" : "string"
                },
                "postalCode" : {
-                  "description" : "The postal code.\nMaximum length:\n* 5 digits for an address in the US.\n* 10 characters for an address in all other countries.\n\nSupported characters: [a-z] [A-Z] [0-9] and Space.\n",
+                  "description" : "The postal code.\nMaximum length:\n* 5 digits for an address in the US.\n* 10 characters for an address in all other countries.\n\nSupported characters: **[a-z] [A-Z] [0-9]** and Space.\n\n> Required for addresses in the US.\n",
                   "minLength" : 3,
                   "type" : "string"
                },
                "stateOrProvince" : {
-                  "description" : "   The two-letter ISO 3166-2 state or province code. For example, **CA** in the US or **ON** in Canada.\n   > Required for the US and Canada.\n",
+                  "description" : "   The two-letter ISO 3166-2 state or province code. For example, **CA** in the US or **ON** in Canada.\n\n   > Required for the US and Canada.\n",
                   "type" : "string"
                }
             },
@@ -1725,6 +1725,11 @@
                   },
                   "type" : "array"
                },
+               "externalReason" : {
+                  "x-addedInVersion" : "3",
+                  "description" : "The external reason of this transfer.",
+                  "$ref" : "#/components/schemas/ExternalReason"
+               },
                "id" : {
                   "description" : "The ID of the resource.",
                   "type" : "string"

json/TransferService-v3.json

@@ -1160,7 +1160,7 @@
             "additionalProperties" : false,
             "properties" : {
                "city" : {
-                  "description" : "The name of the city.\n\nSupported characters: [a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ | and Space.",
+                  "description" : "The name of the city.\n\nSupported characters: **[a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ |** and Space.\n\n> Required when the `category` is **card**.\n",
                   "minLength" : 3,
                   "type" : "string"
                },
@@ -1169,20 +1169,20 @@
                   "type" : "string"
                },
                "line1" : {
-                  "description" : "First line of the street address.\n\nSupported characters: [a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ | and Space.",
+                  "description" : "The first line of the street address.\n\nSupported characters: **[a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ |** and Space.\n\n> Required when the `category` is **card**.\n",
                   "type" : "string"
                },
                "line2" : {
-                  "description" : "Second line of the street address.\n\nSupported characters: [a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ | and Space.",
+                  "description" : "The second line of the street address.\n\nSupported characters: **[a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ |** and Space.\n\n> Required when the `category` is **card**.\n",
                   "type" : "string"
                },
                "postalCode" : {
-                  "description" : "The postal code.\nMaximum length:\n* 5 digits for an address in the US.\n* 10 characters for an address in all other countries.\n\nSupported characters: [a-z] [A-Z] [0-9] and Space.\n",
+                  "description" : "The postal code.\nMaximum length:\n* 5 digits for an address in the US.\n* 10 characters for an address in all other countries.\n\nSupported characters: **[a-z] [A-Z] [0-9]** and Space.\n\n> Required for addresses in the US.\n",
                   "minLength" : 3,
                   "type" : "string"
                },
                "stateOrProvince" : {
-                  "description" : "   The two-letter ISO 3166-2 state or province code. For example, **CA** in the US or **ON** in Canada.\n   > Required for the US and Canada.\n",
+                  "description" : "   The two-letter ISO 3166-2 state or province code. For example, **CA** in the US or **ON** in Canada.\n\n   > Required for the US and Canada.\n",
                   "type" : "string"
                }
             },

json/TransferService-v4.json

@@ -902,6 +902,12 @@
                         "payout-to-balance-account" : {
                            "$ref" : "#/components/examples/post-transfers-payout-to-balance-account"
                         },
+                        "payout-to-card-raw" : {
+                           "$ref" : "#/components/examples/post-transfers-payout-to-card-raw"
+                        },
+                        "payout-to-card-tokenized" : {
+                           "$ref" : "#/components/examples/post-transfers-payout-to-card-tokenized"
+                        },
                         "payout-to-transfer-instrument" : {
                            "$ref" : "#/components/examples/post-transfers-payout-to-transfer-instrument"
                         }
@@ -943,6 +949,12 @@
                            "payout-to-balance-account" : {
                               "$ref" : "#/components/examples/post-transfers-payout-to-balance-account-202"
                            },
+                           "payout-to-card-raw" : {
+                              "$ref" : "#/components/examples/post-transfers-payout-to-card-raw-202"
+                           },
+                           "payout-to-card-tokenized" : {
+                              "$ref" : "#/components/examples/post-transfers-payout-to-card-tokenized-202"
+                           },
                            "payout-to-transfer-instrument" : {
                               "$ref" : "#/components/examples/post-transfers-payout-to-transfer-instrument-202"
                            }
@@ -1519,7 +1531,7 @@
             "additionalProperties" : false,
             "properties" : {
                "city" : {
-                  "description" : "The name of the city.\n\nSupported characters: [a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ | and Space.",
+                  "description" : "The name of the city.\n\nSupported characters: **[a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ |** and Space.\n\n> Required when the `category` is **card**.\n",
                   "minLength" : 3,
                   "type" : "string"
                },
@@ -1528,20 +1540,20 @@
                   "type" : "string"
                },
                "line1" : {
-                  "description" : "First line of the street address.\n\nSupported characters: [a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ | and Space.",
+                  "description" : "The first line of the street address.\n\nSupported characters: **[a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ |** and Space.\n\n> Required when the `category` is **card**.\n",
                   "type" : "string"
                },
                "line2" : {
-                  "description" : "Second line of the street address.\n\nSupported characters: [a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ | and Space.",
+                  "description" : "The second line of the street address.\n\nSupported characters: **[a-z] [A-Z] [0-9] . - — / # , ’ ° ( ) : ; [ ] & \\ |** and Space.\n\n> Required when the `category` is **card**.\n",
                   "type" : "string"
                },
                "postalCode" : {
-                  "description" : "The postal code.\nMaximum length:\n* 5 digits for an address in the US.\n* 10 characters for an address in all other countries.\n\nSupported characters: [a-z] [A-Z] [0-9] and Space.\n",
+                  "description" : "The postal code.\nMaximum length:\n* 5 digits for an address in the US.\n* 10 characters for an address in all other countries.\n\nSupported characters: **[a-z] [A-Z] [0-9]** and Space.\n\n> Required for addresses in the US.\n",
                   "minLength" : 3,
                   "type" : "string"
                },
                "stateOrProvince" : {
-                  "description" : "   The two-letter ISO 3166-2 state or province code. For example, **CA** in the US or **ON** in Canada.\n   > Required for the US and Canada.\n",
+                  "description" : "   The two-letter ISO 3166-2 state or province code. For example, **CA** in the US or **ON** in Canada.\n\n   > Required for the US and Canada.\n",
                   "type" : "string"
                }
             },
@@ -3872,6 +3884,11 @@
                   },
                   "type" : "array"
                },
+               "externalReason" : {
+                  "x-addedInVersion" : "3",
+                  "description" : "The external reason of this transfer.",
+                  "$ref" : "#/components/schemas/ExternalReason"
+               },
                "id" : {
                   "description" : "The ID of the resource.",
                   "type" : "string"
@@ -5551,6 +5568,174 @@
                "status" : "authorised"
             }
          },
+         "post-transfers-payout-to-card-raw" : {
+            "summary" : "Pay out to a third-party card (raw card details)",
+            "description" : "Example request to pay out to a third-party card using raw card details",
+            "value" : {
+               "amount" : {
+                  "value" : 10000,
+                  "currency" : "USD"
+               },
+               "balanceAccountId" : "BA00000000000000000000001",
+               "category" : "card",
+               "counterparty" : {
+                  "card" : {
+                     "cardHolder" : {
+                        "type" : "individual",
+                        "firstName" : "Albert",
+                        "lastName" : "Klaassen",
+                        "address" : {
+                           "city" : "San Francisco",
+                           "country" : "US",
+                           "line1" : "274",
+                           "line2" : "Brannan St",
+                           "postalCode" : "94107",
+                           "stateOrProvince" : "CA"
+                        }
+                     },
+                     "cardIdentification" : {
+                        "number" : "4321123456788765",
+                        "expiryMonth" : "03",
+                        "expiryYear" : "2030"
+                     }
+                  }
+               },
+               "reference" : "Your internal reference for the transfer",
+               "description" : "Your internal description for the transfer"
+            }
+         },
+         "post-transfers-payout-to-card-raw-202" : {
+            "summary" : "Response code - 202 Accepted",
+            "description" : "Example response for a request for a card payout (raw details)",
+            "value" : {
+               "creationDate" : "2023-12-28T15:26:06+01:00",
+               "id" : "48POP561F0ZWWLNW",
+               "accountHolder" : {
+                  "description" : "Your description for the account holder",
+                  "id" : "AH00000000000000000000001"
+               },
+               "amount" : {
+                  "currency" : "USD",
+                  "value" : 10000
+               },
+               "balanceAccount" : {
+                  "description" : "Your description for the balance account",
+                  "id" : "BA00000000000000000000001"
+               },
+               "category" : "card",
+               "counterparty" : {
+                  "card" : {
+                     "cardHolder" : {
+                        "address" : {
+                           "city" : "San Francisco",
+                           "country" : "US",
+                           "postalCode" : "94107",
+                           "stateOrProvince" : "CA",
+                           "line1" : "274",
+                           "line2" : "Brannan St"
+                        },
+                        "firstName" : "Albert",
+                        "lastName" : "Klaassen",
+                        "type" : "individual"
+                     },
+                     "cardIdentification" : {
+                        "expiryMonth" : "03",
+                        "expiryYear" : "2030",
+                        "number" : "432112******8765"
+                     }
+                  }
+               },
+               "description" : "Your internal description of the transfer",
+               "direction" : "outgoing",
+               "reason" : "approved",
+               "reference" : "Your internal reference for the transfer",
+               "status" : "authorised",
+               "type" : "cardTransfer"
+            }
+         },
+         "post-transfers-payout-to-card-tokenized" : {
+            "summary" : "Pay out to a third-party card (tokenized card details)",
+            "description" : "Example request to pay out to a third-party card using tokenized card details",
+            "value" : {
+               "amount" : {
+                  "value" : 10000,
+                  "currency" : "USD"
+               },
+               "balanceAccountId" : "BA00000000000000000000001",
+               "category" : "card",
+               "counterparty" : {
+                  "card" : {
+                     "cardHolder" : {
+                        "firstName" : "Albert",
+                        "lastName" : "Klaassen",
+                        "reference" : "Your reference for the cardholder",
+                        "type" : "individual",
+                        "address" : {
+                           "city" : "San Francisco",
+                           "country" : "US",
+                           "line1" : "274",
+                           "line2" : "Brannan St",
+                           "postalCode" : "94107",
+                           "stateOrProvince" : "CA"
+                        }
+                     },
+                     "cardIdentification" : {
+                        "storedPaymentMethodId" : "ZMV627QSCQVDKG66"
+                     }
+                  }
+               },
+               "reference" : "Your internal reference for the transfer",
+               "description" : "Your internal description for the transfer"
+            }
+         },
+         "post-transfers-payout-to-card-tokenized-202" : {
+            "summary" : "Response code - 202 Accepted",
+            "description" : "Example response for a request for a card payout (tokenized details)",
+            "value" : {
+               "creationDate" : "2024-06-11T16:12:32+02:00",
+               "id" : "4VXLNQ638WU0IAN3",
+               "accountHolder" : {
+                  "description" : "Your description for the account holder",
+                  "id" : "AH00000000000000000000001"
+               },
+               "amount" : {
+                  "currency" : "USD",
+                  "value" : 10000
+               },
+               "balanceAccount" : {
+                  "description" : "Your description for the balance account",
+                  "id" : "BA00000000000000000000001"
+               },
+               "category" : "card",
+               "counterparty" : {
+                  "card" : {
+                     "cardHolder" : {
+                        "firstName" : "Albert",
+                        "lastName" : "Klaassen",
+                        "reference" : "Your reference for the cardholder",
+                        "type" : "individual",
+                        "address" : {
+                           "city" : "San Francisco",
+                           "country" : "US",
+                           "line1" : "274",
+                           "line2" : "Brannan St",
+                           "postalCode" : "94107",
+                           "stateOrProvince" : "CA"
+                        }
+                     },
+                     "cardIdentification" : {
+                        "storedPaymentMethodId" : "ZMV627QSCQVDKG66"
+                     }
+                  }
+               },
+               "description" : "Your internal description of the transfer",
+               "direction" : "outgoing",
+               "reason" : "approved",
+               "reference" : "Your internal reference for the transfer",
+               "status" : "authorised",
+               "type" : "cardTransfer"
+            }
+         },
          "post-transfers-payout-to-transfer-instrument" : {
             "summary" : "Pay out to a transfer instrument",
             "description" : "Example request to pay out to a transfer instrument",

yaml/BalancePlatformTransferNotification-v3.yaml

@@ -117,8 +117,9 @@ components:
       additionalProperties: false
       properties:
         city:
-          description: "The name of the city.\n\nSupported characters: [a-z] [A-Z]\
+          description: "The name of the city.\n\nSupported characters: **[a-z] [A-Z]\
-            \ [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ | and Space."
+            \ [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ |** and Space.\n\
+            \n> Required when the `category` is **card**.\n"
           minLength: 3
           type: string
         country:
@@ -126,14 +127,14 @@ components:
             **US**, **NL**, or **GB**.
           type: string
         line1:
-          description: "First line of the street address.\n\nSupported characters:\
+          description: "The first line of the street address.\n\nSupported characters:\
-            \ [a-z] [A-Z] [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ | and\
+            \ **[a-z] [A-Z] [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ |**\
-            \ Space."
+            \ and Space.\n\n> Required when the `category` is **card**.\n"
           type: string
         line2:
-          description: "Second line of the street address.\n\nSupported characters:\
+          description: "The second line of the street address.\n\nSupported characters:\
-            \ [a-z] [A-Z] [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ | and\
+            \ **[a-z] [A-Z] [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ |**\
-            \ Space."
+            \ and Space.\n\n> Required when the `category` is **card**.\n"
           type: string
         postalCode:
           description: 'The postal code.
@@ -145,14 +146,17 @@ components:
             * 10 characters for an address in all other countries.
 
 
-            Supported characters: [a-z] [A-Z] [0-9] and Space.
+            Supported characters: **[a-z] [A-Z] [0-9]** and Space.
+
+
+            > Required for addresses in the US.
 
             '
           minLength: 3
           type: string
         stateOrProvince:
           description: "   The two-letter ISO 3166-2 state or province code. For example,\
-            \ **CA** in the US or **ON** in Canada.\n   > Required for the US and\
+            \ **CA** in the US or **ON** in Canada.\n\n   > Required for the US and\
             \ Canada.\n"
           type: string
       required:
@@ -1204,6 +1208,10 @@ components:
           items:
             $ref: '#/components/schemas/TransferEvent'
           type: array
+        externalReason:
+          x-addedInVersion: '3'
+          description: The external reason of this transfer.
+          $ref: '#/components/schemas/ExternalReason'
         id:
           description: The ID of the resource.
           type: string

yaml/BalancePlatformTransferNotification-v4.yaml

@@ -141,8 +141,9 @@ components:
       additionalProperties: false
       properties:
         city:
-          description: "The name of the city.\n\nSupported characters: [a-z] [A-Z]\
+          description: "The name of the city.\n\nSupported characters: **[a-z] [A-Z]\
-            \ [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ | and Space."
+            \ [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ |** and Space.\n\
+            \n> Required when the `category` is **card**.\n"
           minLength: 3
           type: string
         country:
@@ -150,14 +151,14 @@ components:
             **US**, **NL**, or **GB**.
           type: string
         line1:
-          description: "First line of the street address.\n\nSupported characters:\
+          description: "The first line of the street address.\n\nSupported characters:\
-            \ [a-z] [A-Z] [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ | and\
+            \ **[a-z] [A-Z] [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ |**\
-            \ Space."
+            \ and Space.\n\n> Required when the `category` is **card**.\n"
           type: string
         line2:
-          description: "Second line of the street address.\n\nSupported characters:\
+          description: "The second line of the street address.\n\nSupported characters:\
-            \ [a-z] [A-Z] [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ | and\
+            \ **[a-z] [A-Z] [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ |**\
-            \ Space."
+            \ and Space.\n\n> Required when the `category` is **card**.\n"
           type: string
         postalCode:
           description: 'The postal code.
@@ -169,14 +170,17 @@ components:
             * 10 characters for an address in all other countries.
 
 
-            Supported characters: [a-z] [A-Z] [0-9] and Space.
+            Supported characters: **[a-z] [A-Z] [0-9]** and Space.
+
+
+            > Required for addresses in the US.
 
             '
           minLength: 3
           type: string
         stateOrProvince:
           description: "   The two-letter ISO 3166-2 state or province code. For example,\
-            \ **CA** in the US or **ON** in Canada.\n   > Required for the US and\
+            \ **CA** in the US or **ON** in Canada.\n\n   > Required for the US and\
             \ Canada.\n"
           type: string
       required:
@@ -1554,6 +1558,10 @@ components:
           items:
             $ref: '#/components/schemas/TransferEvent'
           type: array
+        externalReason:
+          x-addedInVersion: '3'
+          description: The external reason of this transfer.
+          $ref: '#/components/schemas/ExternalReason'
         id:
           description: The ID of the resource.
           type: string

yaml/TransferService-v3.yaml

@@ -827,8 +827,9 @@ components:
       additionalProperties: false
       properties:
         city:
-          description: "The name of the city.\n\nSupported characters: [a-z] [A-Z]\
+          description: "The name of the city.\n\nSupported characters: **[a-z] [A-Z]\
-            \ [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ | and Space."
+            \ [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ |** and Space.\n\
+            \n> Required when the `category` is **card**.\n"
           minLength: 3
           type: string
         country:
@@ -836,14 +837,14 @@ components:
             **US**, **NL**, or **GB**.
           type: string
         line1:
-          description: "First line of the street address.\n\nSupported characters:\
+          description: "The first line of the street address.\n\nSupported characters:\
-            \ [a-z] [A-Z] [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ | and\
+            \ **[a-z] [A-Z] [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ |**\
-            \ Space."
+            \ and Space.\n\n> Required when the `category` is **card**.\n"
           type: string
         line2:
-          description: "Second line of the street address.\n\nSupported characters:\
+          description: "The second line of the street address.\n\nSupported characters:\
-            \ [a-z] [A-Z] [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ | and\
+            \ **[a-z] [A-Z] [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ |**\
-            \ Space."
+            \ and Space.\n\n> Required when the `category` is **card**.\n"
           type: string
         postalCode:
           description: 'The postal code.
@@ -855,14 +856,17 @@ components:
             * 10 characters for an address in all other countries.
 
 
-            Supported characters: [a-z] [A-Z] [0-9] and Space.
+            Supported characters: **[a-z] [A-Z] [0-9]** and Space.
+
+
+            > Required for addresses in the US.
 
             '
           minLength: 3
           type: string
         stateOrProvince:
           description: "   The two-letter ISO 3166-2 state or province code. For example,\
-            \ **CA** in the US or **ON** in Canada.\n   > Required for the US and\
+            \ **CA** in the US or **ON** in Canada.\n\n   > Required for the US and\
             \ Canada.\n"
           type: string
       required:

yaml/TransferService-v4.yaml

@@ -705,6 +705,10 @@ paths:
                 $ref: '#/components/examples/post-transfers-payout-local-transfer-us'
               payout-to-balance-account:
                 $ref: '#/components/examples/post-transfers-payout-to-balance-account'
+              payout-to-card-raw:
+                $ref: '#/components/examples/post-transfers-payout-to-card-raw'
+              payout-to-card-tokenized:
+                $ref: '#/components/examples/post-transfers-payout-to-card-tokenized'
               payout-to-transfer-instrument:
                 $ref: '#/components/examples/post-transfers-payout-to-transfer-instrument'
             schema:
@@ -730,6 +734,10 @@ paths:
                   $ref: '#/components/examples/post-transfers-payout-local-transfer-us-202'
                 payout-to-balance-account:
                   $ref: '#/components/examples/post-transfers-payout-to-balance-account-202'
+                payout-to-card-raw:
+                  $ref: '#/components/examples/post-transfers-payout-to-card-raw-202'
+                payout-to-card-tokenized:
+                  $ref: '#/components/examples/post-transfers-payout-to-card-tokenized-202'
                 payout-to-transfer-instrument:
                   $ref: '#/components/examples/post-transfers-payout-to-transfer-instrument-202'
               schema:
@@ -1102,8 +1110,9 @@ components:
       additionalProperties: false
       properties:
         city:
-          description: "The name of the city.\n\nSupported characters: [a-z] [A-Z]\
+          description: "The name of the city.\n\nSupported characters: **[a-z] [A-Z]\
-            \ [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ | and Space."
+            \ [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ |** and Space.\n\
+            \n> Required when the `category` is **card**.\n"
           minLength: 3
           type: string
         country:
@@ -1111,14 +1120,14 @@ components:
             **US**, **NL**, or **GB**.
           type: string
         line1:
-          description: "First line of the street address.\n\nSupported characters:\
+          description: "The first line of the street address.\n\nSupported characters:\
-            \ [a-z] [A-Z] [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ | and\
+            \ **[a-z] [A-Z] [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ |**\
-            \ Space."
+            \ and Space.\n\n> Required when the `category` is **card**.\n"
           type: string
         line2:
-          description: "Second line of the street address.\n\nSupported characters:\
+          description: "The second line of the street address.\n\nSupported characters:\
-            \ [a-z] [A-Z] [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ | and\
+            \ **[a-z] [A-Z] [0-9] . - \u2014 / # , \u2019 \xB0 ( ) : ; [ ] & \\ |**\
-            \ Space."
+            \ and Space.\n\n> Required when the `category` is **card**.\n"
           type: string
         postalCode:
           description: 'The postal code.
@@ -1130,14 +1139,17 @@ components:
             * 10 characters for an address in all other countries.
 
 
-            Supported characters: [a-z] [A-Z] [0-9] and Space.
+            Supported characters: **[a-z] [A-Z] [0-9]** and Space.
+
+
+            > Required for addresses in the US.
 
             '
           minLength: 3
           type: string
         stateOrProvince:
           description: "   The two-letter ISO 3166-2 state or province code. For example,\
-            \ **CA** in the US or **ON** in Canada.\n   > Required for the US and\
+            \ **CA** in the US or **ON** in Canada.\n\n   > Required for the US and\
             \ Canada.\n"
           type: string
       required:
@@ -3260,6 +3272,10 @@ components:
           items:
             $ref: '#/components/schemas/TransferEvent'
           type: array
+        externalReason:
+          x-addedInVersion: '3'
+          description: The external reason of this transfer.
+          $ref: '#/components/schemas/ExternalReason'
         id:
           description: The ID of the resource.
           type: string
@@ -4709,6 +4725,140 @@ components:
         direction: outgoing
         reason: approved
         status: authorised
+    post-transfers-payout-to-card-raw:
+      summary: Pay out to a third-party card (raw card details)
+      description: Example request to pay out to a third-party card using raw card
+        details
+      value:
+        amount:
+          value: 10000
+          currency: USD
+        balanceAccountId: BA00000000000000000000001
+        category: card
+        counterparty:
+          card:
+            cardHolder:
+              type: individual
+              firstName: Albert
+              lastName: Klaassen
+              address:
+                city: San Francisco
+                country: US
+                line1: '274'
+                line2: Brannan St
+                postalCode: '94107'
+                stateOrProvince: CA
+            cardIdentification:
+              number: '4321123456788765'
+              expiryMonth: '03'
+              expiryYear: '2030'
+        reference: Your internal reference for the transfer
+        description: Your internal description for the transfer
+    post-transfers-payout-to-card-raw-202:
+      summary: Response code - 202 Accepted
+      description: Example response for a request for a card payout (raw details)
+      value:
+        creationDate: '2023-12-28T15:26:06+01:00'
+        id: 48POP561F0ZWWLNW
+        accountHolder:
+          description: Your description for the account holder
+          id: AH00000000000000000000001
+        amount:
+          currency: USD
+          value: 10000
+        balanceAccount:
+          description: Your description for the balance account
+          id: BA00000000000000000000001
+        category: card
+        counterparty:
+          card:
+            cardHolder:
+              address:
+                city: San Francisco
+                country: US
+                postalCode: '94107'
+                stateOrProvince: CA
+                line1: '274'
+                line2: Brannan St
+              firstName: Albert
+              lastName: Klaassen
+              type: individual
+            cardIdentification:
+              expiryMonth: '03'
+              expiryYear: '2030'
+              number: 432112******8765
+        description: Your internal description of the transfer
+        direction: outgoing
+        reason: approved
+        reference: Your internal reference for the transfer
+        status: authorised
+        type: cardTransfer
+    post-transfers-payout-to-card-tokenized:
+      summary: Pay out to a third-party card (tokenized card details)
+      description: Example request to pay out to a third-party card using tokenized
+        card details
+      value:
+        amount:
+          value: 10000
+          currency: USD
+        balanceAccountId: BA00000000000000000000001
+        category: card
+        counterparty:
+          card:
+            cardHolder:
+              firstName: Albert
+              lastName: Klaassen
+              reference: Your reference for the cardholder
+              type: individual
+              address:
+                city: San Francisco
+                country: US
+                line1: '274'
+                line2: Brannan St
+                postalCode: '94107'
+                stateOrProvince: CA
+            cardIdentification:
+              storedPaymentMethodId: ZMV627QSCQVDKG66
+        reference: Your internal reference for the transfer
+        description: Your internal description for the transfer
+    post-transfers-payout-to-card-tokenized-202:
+      summary: Response code - 202 Accepted
+      description: Example response for a request for a card payout (tokenized details)
+      value:
+        creationDate: '2024-06-11T16:12:32+02:00'
+        id: 4VXLNQ638WU0IAN3
+        accountHolder:
+          description: Your description for the account holder
+          id: AH00000000000000000000001
+        amount:
+          currency: USD
+          value: 10000
+        balanceAccount:
+          description: Your description for the balance account
+          id: BA00000000000000000000001
+        category: card
+        counterparty:
+          card:
+            cardHolder:
+              firstName: Albert
+              lastName: Klaassen
+              reference: Your reference for the cardholder
+              type: individual
+              address:
+                city: San Francisco
+                country: US
+                line1: '274'
+                line2: Brannan St
+                postalCode: '94107'
+                stateOrProvince: CA
+            cardIdentification:
+              storedPaymentMethodId: ZMV627QSCQVDKG66
+        description: Your internal description of the transfer
+        direction: outgoing
+        reason: approved
+        reference: Your internal reference for the transfer
+        status: authorised
+        type: cardTransfer
     post-transfers-payout-to-transfer-instrument:
       summary: Pay out to a transfer instrument
       description: Example request to pay out to a transfer instrument